Skip to main content

modelith_plugin_protocol/
manifest.rs

1//! プラグインのマニフェスト(`modelith-plugin.json`)。
2
3use serde::{Deserialize, Serialize};
4
5use crate::PluginId;
6
7/// プラグインのマニフェスト。
8#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
9#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
10#[serde(rename_all = "camelCase", deny_unknown_fields)]
11#[cfg_attr(feature = "codegen", schemars(title = "Modelith plugin manifest"))]
12pub struct PluginManifest {
13    pub id: PluginId,
14    /// 表示名。
15    pub name: String,
16    /// プラグイン自身のバージョン(SemVer)。
17    #[cfg_attr(
18        feature = "codegen",
19        schemars(regex(pattern = r"^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$"))
20    )]
21    pub version: String,
22    /// 対象とするプラグイン API のメジャーバージョン(plugin-sdk のメジャーバージョン)。
23    #[cfg_attr(feature = "codegen", schemars(regex(pattern = r"^\d+$")))]
24    pub api_version: String,
25    pub runtime: Runtime,
26    #[serde(default, skip_serializing_if = "Option::is_none")]
27    #[cfg_attr(feature = "codegen", ts(optional))]
28    pub description: Option<String>,
29    /// 作者の名前。権限を許可する画面などに出す。
30    #[serde(default, skip_serializing_if = "Option::is_none")]
31    #[cfg_attr(feature = "codegen", ts(optional))]
32    pub author: Option<String>,
33    /// SPDX ライセンス式。
34    pub license: String,
35    /// 動く本体の版の範囲。書かなければ、どの版の本体でも動かす。
36    #[serde(default, skip_serializing_if = "Option::is_none")]
37    #[cfg_attr(feature = "codegen", ts(optional))]
38    pub engines: Option<Engines>,
39    /// エントリポイント。`rules` では不要。
40    /// - `browser`: 1 つのファイルにまとめた従来型のスクリプト(例: ESM を IIFE にまとめたもの)。
41    ///   モジュール形式(`import` / `export` を含むもの)は Chromium のサンドボックス化した iframe の中で動かせない(ADR-0018 §3.1)。
42    /// - `wasm-component`: .wasm ファイル。
43    #[serde(default, skip_serializing_if = "Option::is_none")]
44    #[cfg_attr(feature = "codegen", ts(optional))]
45    pub main: Option<String>,
46    /// 要求する権限。宣言していない操作はホストが拒否する。
47    #[serde(default)]
48    #[cfg_attr(feature = "codegen", ts(as = "Option<Vec<Permission>>", optional))]
49    pub permissions: Vec<Permission>,
50    #[serde(default)]
51    #[cfg_attr(feature = "codegen", ts(as = "Option<Contributes>", optional))]
52    pub contributes: Contributes,
53}
54
55/// プラグインが動く本体の版の範囲(本体の ADR-0023 §5)。
56///
57/// 本体の公開の系列(安定版・リリース候補版・プレビュー版)が同時に動くので、新しい本体の機能に頼るプラグインは、
58/// 動く版の範囲をここに書く。範囲の外の本体は、プラグインを動かさずに利用者に知らせる。
59#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
60#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
61#[serde(rename_all = "camelCase", deny_unknown_fields)]
62pub struct Engines {
63    /// Modelith の版の範囲。比べる記号と版をカンマで区切って並べる(Cargo の版の指定と同じ書き方。例: `">=0.1.0, <0.3.0"`・`"^0.2"`・`"0.2.x"`・`"*"`)。
64    /// 桁を `x`・`X`・`*` にすると、その桁から後ろを書かなかったのと同じ。版に付けたプレリリースとビルドの印(`-beta.1`・`+b5`)は比べるときに外す。
65    /// 本体も、自分の版からプレリリースの印を外して比べる(`0.2.0-beta.1` の本体は `0.2.0` として扱う)。
66    #[cfg_attr(
67        feature = "codegen",
68        schemars(regex(
69            pattern = r"^\s*(\*|(=|>=?|<=?|~|\^)?\s*\d+(\.(\d+|[xX*])){0,2}([-+][0-9A-Za-z.-]+)*)(\s*,\s*(\*|(=|>=?|<=?|~|\^)?\s*\d+(\.(\d+|[xX*])){0,2}([-+][0-9A-Za-z.-]+)*))*\s*$"
70        ))
71    )]
72    pub modelith: String,
73}
74
75/// プラグインの実行方式(ADR-0004 の段階に対応)。
76#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
77#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
78#[serde(rename_all = "kebab-case")]
79pub enum Runtime {
80    /// v0: YAML 宣言ルール。コアが解釈するのでブラウザ・CLI・CI のどこでも動く。
81    Rules,
82    /// v1: 1 つのファイルにまとめたスクリプトを、サンドボックス化した iframe の中の Web Worker で実行する。ブラウザのみ。
83    Browser,
84    /// v2: WASM Component。ブラウザ・CLI・サーバで動く。
85    WasmComponent,
86}
87
88/// プラグインが要求できる権限。
89#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
90#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
91pub enum Permission {
92    /// モデル(テキスト・解析結果)を読む。
93    #[serde(rename = "model:read")]
94    ModelRead,
95    /// `TextEdit` による変更案を返す。
96    #[serde(rename = "edits:propose")]
97    EditsPropose,
98    /// ネットワークにアクセスする。
99    #[serde(rename = "network")]
100    Network,
101    /// プラグイン専用の永続ストレージを使う。
102    #[serde(rename = "storage")]
103    Storage,
104}
105
106/// プラグインが追加する機能(拡張点)。
107#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
108#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
109#[serde(rename_all = "camelCase", deny_unknown_fields)]
110pub struct Contributes {
111    /// 検査ルールのファイル(YAML)。
112    #[serde(default, skip_serializing_if = "Vec::is_empty")]
113    #[cfg_attr(feature = "codegen", ts(as = "Option<Vec<String>>", optional))]
114    pub rules: Vec<String>,
115    #[serde(default, skip_serializing_if = "Vec::is_empty")]
116    #[cfg_attr(feature = "codegen", ts(as = "Option<Vec<Importer>>", optional))]
117    pub importers: Vec<Importer>,
118    #[serde(default, skip_serializing_if = "Vec::is_empty")]
119    #[cfg_attr(feature = "codegen", ts(as = "Option<Vec<Exporter>>", optional))]
120    pub exporters: Vec<Exporter>,
121    #[serde(default, skip_serializing_if = "Vec::is_empty")]
122    #[cfg_attr(feature = "codegen", ts(as = "Option<Vec<View>>", optional))]
123    pub views: Vec<View>,
124    #[serde(default, skip_serializing_if = "Vec::is_empty")]
125    #[cfg_attr(feature = "codegen", ts(as = "Option<Vec<PaletteItem>>", optional))]
126    pub palette: Vec<PaletteItem>,
127    #[serde(default, skip_serializing_if = "Vec::is_empty")]
128    #[cfg_attr(feature = "codegen", ts(as = "Option<Vec<Command>>", optional))]
129    pub commands: Vec<Command>,
130}
131
132#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
133#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
134#[serde(rename_all = "camelCase", deny_unknown_fields)]
135pub struct Importer {
136    pub id: String,
137    pub label: String,
138    /// 対応する拡張子(例: `.reqif`)。
139    pub extensions: Vec<String>,
140}
141
142#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
143#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
144#[serde(rename_all = "camelCase", deny_unknown_fields)]
145pub struct Exporter {
146    pub id: String,
147    pub label: String,
148    /// 出力ファイルの拡張子(例: `.drawio`)。
149    pub extension: String,
150}
151
152#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
153#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
154#[serde(rename_all = "camelCase", deny_unknown_fields)]
155pub struct View {
156    pub id: String,
157    pub label: String,
158}
159
160#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
161#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
162#[serde(rename_all = "camelCase", deny_unknown_fields)]
163pub struct PaletteItem {
164    pub id: String,
165    pub label: String,
166    /// 配置時に挿入する SysML v2 テキストの雛形。
167    pub snippet: String,
168}
169
170#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
171#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
172#[serde(rename_all = "camelCase", deny_unknown_fields)]
173pub struct Command {
174    pub id: String,
175    pub title: String,
176}
177
178#[cfg(test)]
179mod tests {
180    use super::*;
181
182    const BASE: &str = r#""id":"a.b","name":"x","version":"0.1.0","apiVersion":"0","runtime":"browser","license":"MIT""#;
183
184    #[test]
185    fn parses_minimal_rules_manifest() {
186        // Arrange
187        let json = r#"{
188            "id": "jp.modelith.iso15288-rules",
189            "name": "ISO 15288 フェーズ検査",
190            "version": "0.1.0",
191            "apiVersion": "0",
192            "runtime": "rules",
193            "license": "MIT",
194            "permissions": ["model:read"],
195            "contributes": { "rules": ["rules/phases.yaml"] }
196        }"#;
197        // Act
198        let m: PluginManifest = serde_json::from_str(json).unwrap();
199        // Assert
200        assert_eq!(
201            (m.runtime, m.permissions, m.contributes.rules),
202            (
203                Runtime::Rules,
204                vec![Permission::ModelRead],
205                vec!["rules/phases.yaml".to_owned()]
206            )
207        );
208    }
209
210    #[test]
211    fn omitted_optional_fields_default_to_empty() {
212        // Arrange(境界値: 必須フィールドのみ)
213        let json = format!("{{{BASE}}}");
214        // Act
215        let m: PluginManifest = serde_json::from_str(&json).unwrap();
216        // Assert
217        assert_eq!(
218            (m.permissions.len(), m.contributes, m.main),
219            (0, Contributes::default(), None)
220        );
221    }
222
223    #[test]
224    fn parses_author() {
225        // Arrange
226        let json = format!("{{{BASE},\"author\":\"Example Inc.\"}}");
227        // Act
228        let m: PluginManifest = serde_json::from_str(&json).unwrap();
229        // Assert
230        assert_eq!(m.author.as_deref(), Some("Example Inc."));
231    }
232
233    #[test]
234    fn omitted_author_is_none() {
235        // Arrange(境界値: 作者を書かない既存のマニフェスト)
236        let json = format!("{{{BASE}}}");
237        // Act
238        let m: PluginManifest = serde_json::from_str(&json).unwrap();
239        // Assert
240        assert_eq!(m.author, None);
241    }
242
243    #[test]
244    fn parses_engines_range() {
245        // Arrange
246        let json = format!("{{{BASE},\"engines\":{{\"modelith\":\">=0.1.0, <0.3.0\"}}}}");
247        // Act
248        let m: PluginManifest = serde_json::from_str(&json).unwrap();
249        // Assert
250        assert_eq!(
251            m.engines.map(|e| e.modelith).as_deref(),
252            Some(">=0.1.0, <0.3.0")
253        );
254    }
255
256    #[test]
257    fn omitted_engines_is_none() {
258        // Arrange(境界値: 範囲を書かない既存のマニフェストは、どの版の本体でも動かす)
259        let json = format!("{{{BASE}}}");
260        // Act
261        let m: PluginManifest = serde_json::from_str(&json).unwrap();
262        // Assert
263        assert_eq!(m.engines, None);
264    }
265
266    #[test]
267    fn rejects_engines_without_modelith_or_with_unknown_host() {
268        // Arrange(異常系: 本体の名前が無い・知らない本体の名前)
269        let missing = format!("{{{BASE},\"engines\":{{}}}}");
270        let unknown = format!("{{{BASE},\"engines\":{{\"modelith\":\"^0.2\",\"cli\":\"^1\"}}}}");
271        // Act / Assert
272        assert!(serde_json::from_str::<PluginManifest>(&missing).is_err());
273        assert!(serde_json::from_str::<PluginManifest>(&unknown).is_err());
274    }
275
276    #[test]
277    fn rejects_unknown_field() {
278        // Arrange
279        let json = format!("{{{BASE},\"extra\":1}}");
280        // Act
281        let result = serde_json::from_str::<PluginManifest>(&json);
282        // Assert
283        assert!(result.is_err());
284    }
285
286    #[test]
287    fn rejects_unknown_permission() {
288        // Arrange
289        let json = format!("{{{BASE},\"permissions\":[\"fs\"]}}");
290        // Act
291        let result = serde_json::from_str::<PluginManifest>(&json);
292        // Assert
293        assert!(result.is_err());
294    }
295
296    #[test]
297    fn rejects_missing_required_field() {
298        // Arrange(境界値: 必須フィールドが 1 つ欠ける)
299        let json =
300            r#"{"id":"a.b","name":"x","version":"0.1.0","apiVersion":"0","runtime":"browser"}"#;
301        // Act
302        let result = serde_json::from_str::<PluginManifest>(json);
303        // Assert
304        assert!(result.is_err());
305    }
306}