診断と規則のリファレンス
English · 日本語(このファイル)
karasu は問題を 2 つのレイヤーの語彙で報告する。
- 規則(rule)は 概念 — 言語が何を許し何を禁じるか(「edge はその所属 ブロックの内側から originate する」)。規則は、著者とこの spec が制約を語る ときの単位である。
- 診断(diagnostic)は メカニズム — 規則の具体的な違反 1 つを検出したとき
に発火する、名前付きの検査(
edge-source-mismatch)。
1 つの規則はしばしば複数の診断で強制され、1 つの診断はちょうど 1 つの規則に 属する。本書は両者を対応づけるカタログである。
本カタログの読み方
Section titled “本カタログの読み方”- 診断コードは安定 API である。
code文字列(例:edge-source-mismatch) は LSP・app・下流ツールが消費する。規則の言い回しに合わせてコードを rename することはしない。規則名は概念、コードは契約であり、両者は別レイヤー(altitude) に位置する。規則がその診断名とは別の言い回しの方が自然なのは想定どおり。 - すべての診断コードは下記いずれか 1 つの規則ファミリーに属し、core が定義
する全コード(
DiagnosticParamsByCode・WarningKind)が本書に現れる。この 完全性は meta-test で強制される(カタログの完全性 を参照)ため、新規コードは カタログ項目なしには出荷できない。 - すべてのコードは短い ID(
KRS001など)をID列に持つ。表示する面が診断の そばに ID を出す(CLI での表示 を参照)ので、locale によらず行から表の行を 引ける。ID は人のための別名で、ツールはcodeで判定する。1 つの ID は 1 つの コードを指し続ける。廃止したコードの ID は 廃止した ID に残し、別のコードに 振り直さない。 発火条件列に具体的なトリガを記す。severity は core が emit する値。面によって severity が変わるコード(lint-styleは error、renderは warning で出す style の 値の検査)は面ごとに書く。ID は 1 つである。
register と severity
Section titled “register と severity”診断は severity を持つ: error / warning / info。
error— モデルを書かれたとおりには受理できない。言語が拒否する構文(parser が 該当構文をモデルから除く。例:node-not-in-context)か、import 先の欠落や id の 重複のようなプロジェクト単位の不備である。原因によらず、error が 1 件でも立って いる間はどの surface も新しい図を出さない。app と VS Code の プレビューは同じビューの直前の有効な図を出し続け、karasu render/karasu subtreeは何も書かずに exit 1、share・serve・nest の描画エンドポイントは 422 を返す。error を直すと描画が再開する。warning— 著者が直すべき実際の欠陥(dangling な参照、スタイル衝突など)。info— 欠陥ではなく 事実。外部の流派が smell と呼びうる構造(共有 database、領域分散など)を、誤りと断じずに surface する。これが 事実 vs 流派 の register 区別である — TPL-1386 を参照。
karasu は未解決参照に対し warn-don’t-error(spec §S6)に従う。未解決の関係は
落とすが、参照元の node は保存し、レンダー全体を失敗させずに warning として報告
する。これは参照についての方針であり、構文の書き方を受理するかどうかは別の問題で
ある。言語が拒否する書き方は error になる
(ADR-2208、
ADR-2501)。
診断はソース位置(loc)を持つことがある。開始位置と終了位置、およびそれらが
指す文書からなる。
- 位置は 1 始まり。
lineとcolumnは、著者がエディタで見るとおり 1 から 数える。別の基準が要る表示面は、自分の境界で 1 度だけ変換する(LSP の 0 始まりの range)。位置を印字するツールは数値をそのまま印字する。 fileは位置が指す文書を名指す。 プロジェクトは複数ファイルにまたがる。 import 先ファイルの診断や、マージ後のモデルで判定される診断(id の一意性 の cross-file 多重判定、cross-reference 解決 の参照判定)は、その構文を宣言した ファイルに anchor する。それはエントリとは限らない。プロジェクトを解決する 過程で生じる診断は、locを持つかぎり必ずfileを絶対パスで持つ。.krs.styleの診断はシートを名指す。fileが無いときは、消費者自身の文書として読む。 これが生じるのは単一文書の 文脈だけである。LSP は開いている文書を 1 つずつ parse し、karasu lint-styleは シートを 1 つ読み、compileはモデルをソーステキストで受け取る。そうした compile が スタイルシートもテキストで受け取ると、どちらの文書にもパスが無いので、シートの parse 診断はそこではlocを持たない(モデルの位置として読まれる位置を持たせない)。locを持たない診断は位置を名指さない。 見つからないファイルに関する診断は、 代わりにそのパスをメッセージに含む(file-not-found、style-file-not-found)。 宣言ではなく id を名指すマージ時の事実(infra-redeclared-across-filesなど)は どちらも持たない。system-property-conflictはlocを持ち、値が負けた側の宣言を指す。
各表示面は位置を次のように印字する。
| 表示面 | 表示する位置 |
|---|---|
CLI(karasu render と、そのエラー報告を共有するコマンド) |
<file>:<line>:<column>。位置に file が無いか、file がエントリである(正規化したパスで比べる)ときは、ユーザーが打った綴りのエントリ。それ以外はそのファイルを作業ディレクトリからの相対パスで示す。 |
CLI(karasu diff) |
診断は <line>:<column>。両方の入力から来るのでファイルは付けない。warning は after のモデルのものだけなので、after の entry を entry として karasu render と同じ規則で表記する: entry はユーザーが打った綴り(stdin から読んだときは -)、それ以外のファイルは作業ディレクトリからの相対パス。 |
| app のプレビューバナーと warning パネル | 開いている文書の位置、または file の無い位置は UI ロケールの行ラベル(英語 Line <line>、日本語 <line> 行目)。それ以外のファイルは <path>:<line>。パスはプロジェクトルートからの相対パスで、プロジェクトの無いモードではエントリのディレクトリからの相対パスになる。比較中のスナップショットは、撮影元のプロジェクト上のパスで示す。 |
| LSP | 文書自身の range(0 始まり)。LSP は単一文書なので file は生じない。 |
Related TPLs: TPL-2715(位置はそれが指す文書と対で初めてアドレスになる。parse が range を作る場所でファイルを載せ、各表示面はそこから読む)。
CLI での表示
Section titled “CLI での表示”人は行を読み、スクリプトとエージェントは JSON を読む。
行。 カタログの診断を出す行は、severity の語の直後にコードの ID を角括弧で 置く:
Error[KRS012]: index.krs:5:1: A top-level user is not allowed (declare it inside a system block)Warning[KRS041]: index.krs:3:3: Edge "A → Ghost" references unknown node "Ghost"; the edge is dropped (the resolved endpoint is kept)theme.krs.style:1:18 error[KRS086]: Invalid hex color ...- ID は locale によらず同じである。下の表の
ID列で引く。 - 行のそれ以外はコマンドごとの形のまま変えない。位置(ソース位置 を参照)、 severity の語の位置と綴り、locale に従うメッセージである。
- ID の無い行はカタログの診断ではない。引数についての通知、
translateの警告、karasu fmtのCannot format: ...がこれに当たる。 - 行は人向けである。形はマイナーリリースで変わりうる(CHANGELOG で知らせる)ので、 スクリプトは行を解析しない。
JSON。 karasu check <file> --format json は、同じ診断を 1 つの JSON として
stdout に出し、カタログの行を stderr に出さない:
{ "schemaVersion": 1, "errorCount": 0, "diagnostics": [ { "id": "KRS041", "code": "unresolved-edge-endpoint", "severity": "warning", "file": "index.krs", "line": 3, "column": 3, "params": { "from": "A", "to": "Ghost", "unresolvedId": "Ghost" }, "message": "Edge \"A → Ghost\" references unknown node \"Ghost\"; the edge is dropped (the resolved endpoint is kept)", "details": [] } ]}diagnosticsは行と同じ順に並ぶ。id、code、severity、params、message、detailsは必ずある。codeはDiagnosticParamsByCodeのキーかWarningKindのメンバーで、paramsはそのコードの型に従う。どちらも locale に よらない。messageとdetailsは locale に従う。detailsはテキストの行に出ない補足 (ストアを共有するサービスなど)で、無ければ[]である。判定はcodeで行い、idやmessageでは行わない。fileは、行がファイルを示すときにある。位置を持つ診断と、位置を持たないDiagnostic(入口のファイルを示す)である。lineとcolumnは位置を持つときに ある。位置を持たないWarningには 3 つとも無い。fileの綴りは行と同じ。errorCountは error の件数である。終了コードはテキストのときと同じで、読める JSON と1はモデルに error があること、読める JSON と0は無いことを表す。- カタログの外の失敗(ファイルが無い、未知のフラグ、想定外の例外)では JSON を
出さず、stderr に行を出して 0 以外で終わる。消費者は、stdout が JSON として
読めないか
schemaVersionが知らない値なら、「診断が 0 件」と読まずに止まる。 - フィールドを足しても
schemaVersionは変えない。フィールドを消す・意味を変える (paramsのキーを含む)ときは上げる。
Related TPLs: TPL-3654(人にはすべての面で短い ID を、機械には JSON のコードを出し、skill はコードで判定する)。
規則ファミリー
Section titled “規則ファミリー”宣言・edge の配置・構造
Section titled “宣言・edge の配置・構造”何をどこに宣言できるか、edge の起点が何でありうるか。service / domain ブロック
内に書いた edge はそのブロックの id を起点にする。infra ブロックと legend は配置
が固定。sync edge は循環してはならない。
| Code | ID | Severity | 発火条件 |
|---|---|---|---|
edge-source-mismatch |
KRS001 | error | service / domain / entity ブロック内の explicit な edge source が所属ブロック id と一致しない(edge origin scope 規則。entity では関連の向き — 起点 = 参照を保持する側 — を強制する)。 |
edge-endpoint-not-at-scope |
KRS002 | warning | edge を宣言したスコープから届かない endpoint(edge endpoint scope 規則)。bare の endpoint は宣言ブロックの peer でなければならない — 例: service 配下の domain である A・B を system スコープで A -> B と書いた場合。source のブロック内に書くか、cross-domain の entity 参照は限定子付きにする。qualified の endpoint はトップレベル root を起点に anchor されていなければならず(system から対象までの path を丸ごと綴る)、メッセージは anchor された綴りを示し、参照先が宣言されている場所を伝える。entity ブロック内の限定子付きの関連は対象外 — entity ビューが自身の pool で解決し、外部 entity を ghost として描く。どこにも解決しない id は対象外(bare は unresolved-edge-endpoint、system スコープの edge の dotted は cross-system-ref-unresolved が担当(先頭のセグメントがその system の [external] の子なら報告しない)。service・domain・entity の中の dotted は、いまは報告されない。#3655)。bare の domain → domain は暗黙の service edge に集約されて描画されるため除外。 |
edge-target-ambiguous |
KRS003 | warning | qualified な edge endpoint が、スコープの届く範囲の中で (kind, 深さ) の揃わない複数ノードに一致した(#2088 共通の判別子。揃った多重一致は意図された broadcast として沈黙する)。メッセージは候補の full path を列挙し、さらに修飾して絞り込めるよう促す。bare は ambiguity を出さない — peer 束縛を維持しており、そこでの多重一致は既存の broadcast であって新しい問いではない。 |
ambiguous-edge-base |
KRS004 | warning | 同じ from → to の base を持つ edge が複数あり、識別する author id が無い。 |
duplicate-edge-label |
KRS005 | error | エッジが label を 2 回書いている(位置引数 A -> B "calls" と property block 内の label プロパティの両方)。どちらかを黙って勝たせることはしないので、片方に寄せる。 |
service-outside-system |
KRS006 | warning | service が system の外で宣言されている。 |
infra-not-in-context |
KRS007 | error | infra ブロック(database / queue / storage)が system の直接の子でない。 |
boundary-not-in-context |
KRS008 | error | 自身のキャンバスを持たない kind(entity / resource / user / client / infra leaf)の中に boundary ブロックが宣言されており、囲む対象が存在しない。 |
entity-not-in-domain |
KRS009 | error | entity が domain の子以外の場所で宣言されている。 |
node-not-in-context |
KRS010 | error | 論理ノードが、その親の 含められるもの 列に載っていない入れ子で宣言されている(例: service 直下の usecase)。ノードは subtree ごとモデルから除かれる。後続は通常どおりパースされ、そのノードへの参照は §S6 で報告される。言語 v1.x ではノードを保持する warning だったが、.krs language v2.0 から error(#2924)。 |
legend-not-top-level |
KRS011 | error | legend ブロックがトップレベル以外で宣言されている。 |
top-level-declaration |
KRS012 | error | user またはエッジが system ブロック内ではなくトップレベルで宣言されている。 |
system-property-conflict |
KRS013 | warning | merge された import 間で system の label / description が衝突する。 |
cyclic-dependency |
KRS014 | warning | sync edge(->)が依存の循環を形成する。 |
Related TPLs: TPL-2542(同じ意味を 2 通りで書けるようにしたら、両形が同一 AST に落ちること・二重記述に専用の診断があることを同じ PR で固定する。
duplicate-edge-labelはその診断側)。
id の一意性
Section titled “id の一意性”id は宣言 scope 内で一意であること。ownership は primary owner を高々 1 つに割り 当てる。
| Code | ID | Severity | 発火条件 |
|---|---|---|---|
duplicate-edge-id |
KRS015 | error | author 指定の edge id が別の edge id と衝突する。 |
duplicate-node-id-parent |
KRS016 | error | node id が直近の親の中で重複する(1 つの domain 配下で usecase と entity が同じ id を持つケースも含む)。 |
entity-anchor-collision |
KRS017 | warning | entity deep-link の名前空間({全 domain id} ∪ {全 entity id})で id が複数のターゲットに使われている — entity id が複数 domain にまたがって重複、または entity id が domain id と一致。deep-link の解決が曖昧になるが描画自体は成立する。 |
duplicate-node-in-system |
KRS018 | error | node id が system 内で重複する。 |
duplicate-node-in-deploy |
KRS019 | error | node id が deploy ブロック内で重複する。 |
duplicate-team-id |
KRS020 | error | team id が重複する。 |
duplicate-team-in-organization |
KRS021 | error | team id が organization 内で重複する。 |
duplicate-resource-operation |
KRS022 | warning | 1 つの resource に CRUD verb が複数回並ぶ。 |
duplicate-crud-decoration-target |
KRS023 | warning | CRUD decoration が同じ operation を複数回対象にする。 |
duplicate-owner-assignment |
KRS024 | info | node が複数の team に owned として割り当てられる(事実。ADR-1566 参照)。 |
duplicate-boundary-assignment |
KRS025 | info | node が複数の boundary に所属する(事実。所属は 1:N — ビュー側の解決規則は syntax.ja.md を参照)。 |
boundary-membership-not-drawn |
KRS026 | info | Group by: boundary で、非メンバーを覆わずに boundary の枠をメンバーまで広げられなかったため、その所属をカード上の ◇ タブで示した。model の事実を述べる duplicate-boundary-assignment と違い、この描画が何をしたかを述べる。したがって位置情報を持たず、この軸でのみ出る。 |
duplicate-boundary-id |
KRS027 | error | 同じ親ノード内の 2 つの boundary ブロックが同じ id を宣言しており、2 つ目を指し示せない。top-level のブロックは対象外。 |
duplicate-facet-id |
KRS028 | error | 2 つの facet ブロックが同じ id を宣言しており、facets の参照がどちらのメタデータを指すか決まらない。マージ後のモデルで判定するのでファイルをまたぐ重複も検出する。参照が解決するのは最初の宣言。 |
positional-label-removed |
KRS029 | 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 |
KRS030 | warning | 同じ id を持つ論理層ノード(service / domain / client)が異なるパスに複数宣言されている。warning は宣言順にもファイルの分け方にも依存しない(parse 経路はそのファイルで判定し #2550、project 経路はマージ後のモデルで判定し直す #2596。ブロックを別ファイルへ移しても沈黙しなくなった)。マージ後のモデルで判定することは同時に限界でもあり、判定の対象はモデルに到達した宣言に限られる。named import が持ち込まなかった部分に閉じた衝突は project では報告しない(そこでは描画も航法もされないため。エディタは per-file で報告し続ける)。1 つの宣言は、それを運ぶ merge 経路が何本あっても 1 件と数える。同じファイルを wildcard と named の両方で import した場合や、1 つの service が edge 参照で 2 つの system に載る場合は衝突ではない。論理層と物理層(database / queue / storage とその子リソース)の間の同名、および物理層内の同名は許容して沈黙する(物理参照は resource OrderDB.users のように dot 修飾されるため)。domain 同士の多重は対象外(domain-dispersal(info)の領分)。同一の親の下での id 重複は duplicate-node-id-parent(error)に譲るが、top-level の同名はそれを報告する親スコープが無いため、parked な service X と client X の組はこちらで報告する。nodePathIndex は id ごとに勝者 1 つを保持する: @migration_target 優先(infra の子はブロックのアノテーションを継承)、同点は traversal 順(systems → top-level の domains / services / clients → top-level infra。ファイルをまたぐ場合はマージ後のモデルの順、すなわち entry ファイル自身の宣言の後に import されたものが続く)で最初の宣言。したがって candidate の priority が異なる場合、すなわち本来の用途である移行共存のケースでは entry はファイルの分け方に依存しない。priority が同点のときだけ import グラフに従うので、無印の宣言 2 件はファイルを入れ替えると勝者も入れ替わる。負けた論理層の宣言ごとにその位置で warning が 1 つ出る。複数 system のルートビューはすべての宣言を描く(#2917)。各カードは bare の data-node-id を保ったまま data-node-path(Shop.Api)を足すので、クリックはそのカード自身のノードにドリルし、そのノードを説明する。bare id だけを運ぶ hand-over(ハイライト・アウトライン・permalink)は index の勝者か、一致する最初の要素に着く。静的ドリルダウンバンドルは id ごとに #krs-system-<id> / #krs-entity-<id> のレベルを index の勝者について 1 つだけ出すので、その anchor は app と同じノードを開く。勝者でない同名のカードはリンクを持たずに描かれる(#2933)。 |
Related TPLs: TPL-1583(1:1 index の勝者規則は index 間で一貫させる。
node-id-multiple-locationsの勝者規則もその一つ)、TPL-2221(2 ファイルに分かれた重複はどちらのファイルからも見えないので、判定とそれが説明する index はマージ後のモデルで 1 度だけ導出する)。
cross-reference 解決(warn-don’t-error, §S6)
Section titled “cross-reference 解決(warn-don’t-error, §S6)”参照された id は宣言済み node に解決されること。解決できない場合、参照元 node は 保存し、未解決の関係を報告する(致命的エラーにはしない)— syntax spec §S6 参照。
| Code | ID | Severity | 発火条件 |
|---|---|---|---|
owns-target-not-found |
KRS031 | warning | team が、マージ後のモデルでどのノードも指さない id を owns する。kind と深さは問わないため、宣言済みの user や entity はここでは「見つかる」扱いで、kind による拒否は invalid-owns が行う。capability はノードではなくプロパティなのでどのノードにも解決せず、ここで報告される。マージ後のツリーから導出するため、判定は import の書き方にも宣言位置にも依存しない。import 結合の診断であり、未解決の import が残るドキュメントでは判定しない(LSP の単一ドキュメント文脈では沈黙し、App / CLI がマージ後モデルで判定する)。 |
invalid-owns |
KRS032 | 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 |
KRS033 | warning | import 結合の診断であり、未解決の import が残るドキュメントでは判定しない(member が import 先で宣言されている場合があり、スコープ内 contains が名指す子は cross-file の system 再オープンで後から増えうる)。それ以外の場合: boundary の contains 先が存在しない — top-level ブロックはマージ後の system 階層のどこにも無い場合(存在検証は per-file でなく cross-file マージ後)、スコープブロックは宣言ノードの直下の子に無い場合(照合はノード参照 path 記法の接尾辞規則)。 |
owns-target-ambiguous |
KRS034 | warning | owns の参照(接尾辞 path。bare id を含む)が (kind, 深さ) の揃っていない 2 つ以上のノードに解決される。揃っている多重一致は意図的な broadcast(移行共存・マルチテナント)であり沈黙する。メッセージは各候補の full path を列挙し、著者はより長い path で修飾して 1 つに絞れる。owns-target-not-found と同じく import 結合: マージ後モデルでのみ判定する。 |
contains-target-ambiguous |
KRS035 | warning | owns-target-ambiguous の contains 版(top-level boundary 用): kind または深さの混在する多重一致を候補 full path つきで報告する。揃っている多重一致は broadcast として沈黙。スコープ形では構造的に到達不能(member は sibling 一意な直下の子に解決される)。import 結合: マージ後モデルでのみ判定する。 |
realizes-target-ambiguous |
KRS036 | warning | realizes の参照(接尾辞 path。bare id を含む)が realizable な kind(service / domain / client / infra ブロック)の 2 つ以上のノードに解決され、(kind, 深さ) が揃っていない。候補は full path で列挙する。揃っている多重一致は沈黙。存在検査は unresolved-realizes の担当。import 結合: マージ後モデルでのみ判定する。 |
import-target-ambiguous |
KRS037 | warning | 複数セグメントの import { … } エントリが接尾辞規則で (kind, 深さ) の揃わない 2 つ以上のノードに一致した。一致はすべて import される(bare id の import は元々 broadcast)。warning が候補 full path を列挙し、著者は path 修飾で絞れる。 |
facet-not-declared |
KRS038 | warning | facets の参照先の facet ブロックが宣言されていない(存在検証はマージ後のモデルで行うので、import 先の宣言も有効)。near-miss の annotation ヒントと違い、宣言集合が「正」を与えるためこの検査は完全で、著者定義の名前どうしの取り違えも検出する。報告位置は参照を書いた要素(ノードまたはエッジ)の宣言位置で、facets の行そのものではない — 他の要素単位の診断と同じ範囲になる。名指しはノードなら node id、エッジなら(エッジ自身の id が無いので)canonical base 形(A-->B)で、これは edge#<id> が同じエッジを指すのと同じ綴り。 |
import-id-not-found |
KRS039 | error | named import の id パスが解決できない。 |
import-path-not-found |
KRS040 | error | import パスがいずれかのセグメントで解決できない。 |
unresolved-edge-endpoint |
KRS041 | warning | edge の端点 id が merge 後のモデルのどこにも見つからない。 |
unresolved-handles |
KRS042 | warning | handles 対象の domain が one-hop expose 規則で到達できない。参照はノード参照 path で、system 直下の子のさらに直下にある domain を対象に解決し、警告は参照そのものに anchor する(handles A, B の片方だけが失敗しうる)。owns / contains / realizes と違い handles に *-target-ambiguous は無い: この対象集合では候補がすべて同じ深さの domain なので多重一致は構造上つねに揃っており(マルチテナントの broadcast)、より長い path で修飾するという対処が成立しないため。対象集合の外にある domain を名指した参照は ambiguity ではなく本コードで報告する。 |
unresolved-realizes |
KRS043 | warning | deploy node が論理層に無い対象を realizes する。 |
legend-ref-unresolved |
KRS044 | warning | legend の ref がどのスタイル規則にも node にも一致しない。 |
cross-system-ref-unresolved |
KRS045 | warning | cross-system edge(Sys.Svc)の対象が見つからない。 |
cross-system-ref-implicit-external |
KRS046 | warning | cross-system edge が [external] 未付与の system に跨る。 |
delivers-target-not-client |
KRS047 | warning | delivers の対象が client node でない。 |
unresolved-resource-ref |
KRS048 | warning | dot 記法の resource <Parent>.<Child> が、merge 後のモデルに宣言されていない infra ブロックでも client でもない親、または親が宣言していない子(infra ブロックの leaf か、client の storage の id。#3794。parentKind がどちらかを示す)を指している。どちらが欠けているかをメッセージに出す — 修復が異なるため(ブロックごと欠けていれば database / queue / storage 宣言そのものの喪失、leaf だけなら sub-resource の欠落)。[external] の resource は unassigned-resource と揃えて対象外。import-coupled — 共有 infra は各スライスが import する専用ファイルで宣言するのが正準形(§S4.5)なので、単一ドキュメントでは判定しない。 |
resource-target-ambiguous |
KRS115 | warning | resource <Parent>.<Child> の親が 1 つに決まらない(#3794)。infra-and-client: scope の違う infra ブロックと、id 付きの storage を宣言した client が同じ id を持つ。参照は client が解決先になる前と同じく infra ブロックを指し(leaf が無ければ unresolved-resource-ref のまま)、client の storage は参照できない。multiple-clients: 同じ id の client ノード(KRS018 / KRS030)の 2 つ以上が子を宣言しているので、参照は解決しない。[external] の resource は対象外。import 結合: マージ後モデルでのみ判定する。 |
unresolved-table-ref |
KRS049 | warning | entity の table <Infra>.<Leaf> が未宣言のブロック / leaf を指している。missing の区別・[external] 除外・import-coupling は unresolved-resource-ref と同じ。table を 持たない entity は正当な状態(forward design、read-model projection、KV backed)なのでここでは一切報告しない — 数えるのは karasu coverage の役割。 |
infra の単一宣言・fan-in
Section titled “infra の単一宣言・fan-in”infra node は 1 度だけ宣言される。複数 service から参照される store は surface する価値のある事実。
| Code | ID | Severity | 発火条件 |
|---|---|---|---|
infra-redeclared-across-files |
KRS050 | info | 同じ database / queue / storage id が複数の merge 対象ファイルで宣言される。2 つ目の宣言をどの import 形が持ち込んだかに依らず報告する(ファイル全体の import でも、path が当該ブロックを根とする named entry import { UserDB.users } でも同じ)。1 つの宣言を 2 つの entry で名指した場合は reopen ではなく 1 回の import として扱う。 |
infra-leaf-redeclared-silently |
KRS051 | info | table / queue-item / bucket の leaf が親 infra 内で再宣言される。 |
shared-infra-fan-in |
KRS052 | info | 2 つ以上の service が 1 つの system 内で同じ store に依存する(欠陥ではなく事実)。 |
cross-domain-store-access |
KRS053 | info | ある domain の usecase が、別の domain が所有する infra leaf を読み書きする(1 system 内。欠陥ではなく境界越えの事実)。所有は entity マッピングから導出、leaf 粒度で判定、[external] と役割タグ付き([index] / [cache] / [analytics])の store は除外。shared-infra-fan-in とは直交。 |
CRUD decoration の文法
Section titled “CRUD decoration の文法”resource への operation / CRUD decoration の文法。
| Code | ID | Severity | 発火条件 |
|---|---|---|---|
invalid-crud-decoration |
KRS054 | error | CRUD decoration が認識されない verb / letter を使う。 |
empty-crud-decoration |
KRS055 | error | verb: decoration の右辺が空。 |
unknown-resource-operation |
KRS056 | warning | resource operation の verb が create / read / update / delete のいずれでもない。 |
割り当てと凝集
Section titled “割り当てと凝集”構造 node が owner / 親に割り当てられているか、domain と deploy 対象の配線に関する 凝集の事実。
| Code | ID | Severity | 発火条件 |
|---|---|---|---|
unassigned-service |
KRS057 | warning | service が team 割り当てなしにトップレベルに置かれる。 |
unassigned-domain |
KRS058 | warning | domain がどの service にも割り当てられていない(トップレベル、または system 直下に置かれている)。2 つの配置は同じモデリング状態を表すため両方で発火する(#2184)。(Unassigned) 擬似 system に包まれるのはトップレベル形のみ。 |
unassigned-client |
KRS059 | warning | client が team 割り当てなしにトップレベルに置かれる。 |
unassigned-database |
KRS060 | warning | database が team 割り当てなしにトップレベルに置かれる。 |
unassigned-queue |
KRS061 | warning | queue が team 割り当てなしにトップレベルに置かれる。 |
unassigned-storage |
KRS062 | warning | storage が team 割り当てなしにトップレベルに置かれる。 |
unassigned-resource |
KRS063 | warning | bare resource <id> がどのストアにも解決しない(dot-notation でも [external] でも一意な entity でもない)。parser ではなく resolver がモデル全体で判定するため、一致する entity が宣言されると編集ゼロで昇格し警告は消える。曖昧(一致する entity が複数)な bare id は未解決のまま残り、衝突自体は entity-anchor-collision が報告する。 |
domain-dispersal |
KRS064 | info | 1 つの domain id が scope 内の複数 service にまたがる(事実)。 |
missing-realizes |
KRS065 | info | deploy node に realizes プロパティが無い。 |
missing-runtime |
KRS066 | info | deploy node に runtime プロパティが無い。 |
annotation・lifecycle
Section titled “annotation・lifecycle”annotation パラメータ、削除・非推奨になったプロパティ、および閉じた tag /
annotation 語彙(.krs language v2.0 はツール語彙のみを受理する。
tags-annotations.ja.md 参照)。
| Code | ID | Severity | 発火条件 |
|---|---|---|---|
annotation-param-unsupported |
KRS067 | warning | annotation のパラメータ key がその annotation で認識されない。 |
annotation-param-value-unreadable |
KRS068 | warning | 認識される annotation パラメータの値が、文字列リテラル 1 つでも裸の語 1 つでもない(until: 2026-12-31、from: system、from: Shop.Legacy)。何も記録しない。描画は止まらない。AST を出力すると値が消えるため、karasu fmt はファイルを書き換えない。 |
annotation-param-conflict |
KRS069 | warning | 1 つの要素が同じ annotation パラメータに異なる 2 つの値を与えている(アノテーションを繰り返した場合も、1 つの中で繰り返した場合も)。最初の値を保ち、karasu fmt は最初の値を後の値に上書きして出力せず、ファイルを書き換えない。 |
duplicate-annotation |
KRS070 | warning | 同じ annotation が 1 つの要素に複数回書かれている。2 回目以降は効果を持たない。 |
annotation-possible-typo |
KRS071 | error | 非 builtin の annotation 名が builtin 名の綴り誤り(@depracated)である。4 文字以下の builtin なら 1 編集以内、それより長ければ 2 編集以内(隣接する 2 文字の入れ替えは 1 編集と数える)。annotation は適用されずモデルから除かれ、メッセージが builtin 名を示す。抑制条件なし。言語 v1.x では info のヒントだったが、.krs language v2.0 から error になり、annotation-not-builtin とは排他になった。 |
tag-not-builtin |
KRS072 | warning | tag 名がツール語彙(builtin + system-assigned tag)の外にある。パースは通るが効果を持たない(.krs language v2.0 は tag の register をツール語彙に閉じる)。抑制条件なし。 |
tag-not-applicable |
KRS073 | warning | 組み込み tag が適用範囲外の kind に書かれている(例: service Api [index] — [index] は database に適用)。その場所では効果を持たない。tag-not-builtin と同時には発火しない(builtin 外の名前には違反する適用範囲が無いため)。 |
annotation-not-builtin |
KRS074 | warning | annotation 名が builtin 集合の外にあり、builtin 名の綴り誤りでもない(綴り誤りは annotation-possible-typo)。パースは通るが効果を持たない。抑制条件なし。 |
style-tag-selector-not-builtin |
KRS075 | warning | .krs.style のセレクタがツール語彙の外の tag 名を狙っている(例 [pci] { … })。そのルールは何にも一致しない(.krs language v2.0。v1.x までは適用されていた)。この warning がそれを知らせる唯一の手がかりである。facet セレクタ([facets=<id>])へ移行する。モデル側の tag-not-builtin とは独立にセレクタ単位で発火する(両者は別々の編集を指しており、片方だけ警告すると残った方が見つからない)。builtin テーマや注入された system sheet では発火しない。 |
style-annotation-selector-not-builtin |
KRS076 | warning | .krs.style のセレクタが builtin 集合の外の annotation 名を狙っている(例 @canary { … })。契約は style-tag-selector-not-builtin と同じ。 |
team-property-removed |
KRS077 | error | 削除済みの team プロパティが使われる(ADR-1564 参照)。 |
import とファイル
Section titled “import とファイル”import 宣言とスタイル import をファイルシステムに対して解決する。
| Code | ID | Severity | 発火条件 |
|---|---|---|---|
circular-import |
KRS078 | warning | node import が循環を形成する。 |
file-not-found |
KRS080 | error | import されたファイルが存在しない。 |
directory-not-found |
KRS081 | error | import されたディレクトリが存在しない。 |
style-file-not-found |
KRS082 | warning | import されたスタイルファイルが存在しない。 |
スタイル検証
Section titled “スタイル検証”.krs.style のプロパティ名と値を検証する。著者のシートで下の error に当たる宣言は効かない: cascade がその宣言を外すので、弱いルールがそのプロパティに書いた値が効き、どのルールも書いていなければ既定が残る(#3141)。karasu が同梱するシートは検証しない。
| Code | ID | Severity | 発火条件 |
|---|---|---|---|
style-unknown-property |
KRS083 | warning | スタイルのプロパティ名が認識されない。 |
style-unknown-icon |
KRS084 | warning | shape: url("<name>") がどの登録済みアイコンにも一致せず、ノードが box で描かれる。組み込みアイコンは core 自身が登録するので、どの描画面でも同じ結果になる(TPL-2802)。 |
style-invalid-enum-value |
KRS085 | error(lint-style / tidy-style)、warning(render / check) |
スタイル値が許可された enum に無い。 |
style-invalid-hex-color |
KRS086 | error(lint-style / tidy-style)、warning(render / check) |
スタイルの hex color が不正。 |
style-invalid-length-unit |
KRS087 | error(lint-style / tidy-style)、warning(render / check) |
スタイルの length が許可されない単位を使う。 |
style-missing-length-unit |
KRS088 | error(lint-style / tidy-style)、warning(render / check) |
スタイルの length に必要な単位が無い。 |
style-out-of-range |
KRS089 | error(lint-style / tidy-style)、warning(render / check) |
スタイルの数値が min / max の範囲外。 |
style-token-type-mismatch |
KRS090 | error | スタイルの token が期待された型と一致しない。値の中(値として持てない token、空の値、空のカンマ項目)なら宣言は無視される。 |
expected-style-property-name |
KRS091 | error | スタイルパーサがプロパティ名を期待した。 |
expected-semicolon-between-properties |
KRS092 | error | スタイルパーサがプロパティ間の ; を期待した。 |
unknown-edge-selector-attribute |
KRS093 | error | セレクタが from / to / facets 以外の属性を使っている(例: edge[source=X])。コード名は facets より前からあるもので、facets は edge 限定ではなくノードセレクタでも受理される。 |
style-conflict |
KRS094 | warning | セレクタが複数のユーザースタイルシートで定義される。 |
style-column-ignored-non-system-view |
KRS095 | warning | column ヒントが deploy / org ビューに適用される(無視)。 |
Related TPLs: TPL-2802(
style-unknown-iconが引くシェイプレジストリの組み込みの中身は core 自身が埋めるので、判定はどの描画面でも同じになる), TPL-1503(パーサが受理する値は効果か診断を持ち、黙って無視されることはない), TPL-3141(値の範囲はスキーマ 1 か所にだけ置き、拒否した宣言は 1 回だけ外すので、診断が描画を説明する)。
client・capability
Section titled “client・capability”client サブ言語: storage kind と capability。
| Code | ID | Severity | 発火条件 |
|---|---|---|---|
client-resource-invalid-kind |
KRS096 | error | client の resource storage kind が予約値のいずれでもない。 |
client-capability-duplicate |
KRS097 | warning | client が同じ capability 名を 2 度宣言する。 |
client-resource-duplicate-id |
KRS116 | warning | client が同じ id の storage resource を 2 つ宣言する(#3794)。resource <ClientId>.<Id> は最初のものに解決する。1 つの client ノードの行どうしだけを比べる。 |
構文・パースレベルのエラー
Section titled “構文・パースレベルのエラー”token が妥当な構文を成さないときに上がる低レベルのパーサエラー。本質的にメカニズム レベルであり、「規則」は文法そのもの。
| Code | ID | Severity | 発火条件 |
|---|---|---|---|
token-type-mismatch |
KRS098 | error | token がパーサの期待した型と一致しない。 |
unexpected-token-root |
KRS099 | error | root レベルに予期しない token。 |
unexpected-token-in-block |
KRS100 | error | ブロック内に予期しない token。 |
expected-brace-or-string |
KRS101 | error | パーサが { か string literal を期待した。 |
expected-identifier |
KRS102 | error | パーサが identifier を期待した。 |
expected-string-after |
KRS103 | error | パーサがプロパティ keyword の後に string を期待した。 |
expected-id-or-string |
KRS104 | error | パーサが id か string を期待した。 |
expected-node-id |
KRS105 | error | パーサが node id を期待した。 |
expected-property-value |
KRS106 | error | パーサがプロパティ値を期待した。 |
expected-id-after |
KRS107 | error | パーサがプロパティ keyword の後に id を期待した。 |
infra-path-too-long |
KRS108 | error | table 対応や resource 参照が <Infra>.<Leaf> の leaf より先に続く(3 段目、または leaf の後のドット)。 |
invalid-node-kind |
KRS109 | error | node kind の keyword が認識されない。 |
property-not-for-node-kind |
KRS110 | error | プロパティがその node kind に対して妥当でない。 |
link-url-scheme-not-allowed |
KRS111 | warning | link URL の scheme が許可集合(http / https / mailto)に無い。 |
アプリケーションレベルのフォールバック
Section titled “アプリケーションレベルのフォールバック”throw された compile / parse エラーを app が包むときに使う合成コード。
| Code | ID | Severity | 発火条件 |
|---|---|---|---|
app-project-compile-error |
KRS112 | error | compile() が throw し、app が汎用の compile 失敗を報告する。 |
app-org-parse-error |
KRS113 | error | org パースが throw し、app が汎用の parse 失敗を報告する。 |
generic-text |
KRS114 | error | 構造化パラメータを持たない、事前生成のフォールバックメッセージ文字列。 |
カタログの完全性
Section titled “カタログの完全性”DiagnosticParamsByCode と WarningKind(packages/core/src/types)の全メンバーは、
本書に code として現れなければならない。meta-test
(packages/core/src/types/diagnostics-catalog.test.ts)が双方向でこれを assert
するため、カタログが emit されるコードから無言で drift することはない。背景の規律は
TPL-1623
に記録する。
同じ meta-test が、各行の ID が登録簿(packages/core/src/types/diagnostic-ids.ts)
の与える ID であることと、廃止した ID がすべて下に載っていることを確かめる。
廃止した ID
Section titled “廃止した ID”コードを廃止したときは、その行をここへ移し、先頭の列に ID、続けて旧コードを書く
(| KRS000 | `old-code` |)。古い出力の ID からも引け、番号は別のコードに振り直さない。
| ID | Code | 廃止の理由 |
|---|---|---|
| KRS079 | circular-style-import |
スタイルシートは @import を書けないので、スタイル import は循環しない。同じシートに 2 度届いたとき(1 つのファイルが 2 回 import しても、2 つのファイルが import しても)に誤って出ていた(#3513)。 |
Related TPLs: TPL-1623(カタログ ↔ コードの完全性), TPL-1386(事実 vs 流派の register), TPL-2171(spec が約束する診断は実装されている), TPL-1296(spec ↔ source-of-truth 同期).
© 2026 Hiroki Kondo · Licensed underApache-2.0