modelith-plugin-protocol 0.1.0

Contract between Modelith and its plugins: manifest, registry entry, rule set, edit and message types
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
//! 検査ルールのファイル(マニフェストの `contributes.rules` が指す YAML、ADR-0018 §2)。
//!
//! 解釈は modelith-core だけが行う。ここでは形だけを定め、正規表現の妥当性や
//! `min <= max` などの意味の検査は modelith-core が位置つきで報告する。
//! 未知のキーは黙って捨てず、誤りとして返す(すべての構造体が `deny_unknown_fields`)。

use std::fmt;

use serde::{Deserialize, Serialize};

use crate::DiagnosticSeverity;

/// ルール ID の正規表現(英小文字・数字・`-`、英小文字か数字で始まる)。
pub const RULE_ID_PATTERN: &str = r"^[a-z0-9][a-z0-9-]*$";

/// 検査ルールのファイル。
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[cfg_attr(feature = "codegen", schemars(title = "Modelith rule set"))]
pub struct RuleSet {
    pub rules: Vec<Rule>,
}

/// 1 つの検査ルール。`match` に当たる要素ごとに `require` を確かめ、満たさなければ診断を出す。
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct Rule {
    /// プラグインの中で一意な ID。診断の `code` になる。
    pub id: RuleId,
    pub severity: DiagnosticSeverity,
    /// 診断のメッセージ。`{name}`(要素名)と `{kind}`(要素の種類)を差し込める。
    pub message: String,
    /// ルールを当てる要素。
    #[serde(rename = "match")]
    pub target: ElementMatch,
    /// 当たった要素が満たすべき条件。
    pub require: Requirement,
}

/// ルールを当てる要素の条件(すべてを満たす要素に当てる)。
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct ElementMatch {
    /// 要素の種類(例: `requirement def`)。並びはいずれかに当たればよい。
    pub kind: OneOrMany,
    /// 工程(`@Phase`)の名前(例: `SystemRequirements`)。
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "codegen", ts(optional))]
    pub phase: Option<String>,
    /// 要素名の正規表現。
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "codegen", ts(optional))]
    pub name: Option<String>,
}

/// 当たった要素が満たすべき条件(書いたものすべて)。
///
/// 語彙は任意フィールドの追加で増やす(互換を保つ)。
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct Requirement {
    /// この種類の関係(例: `satisfy`)を 1 本以上受ける。並びはいずれかでよい。
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "codegen", ts(optional))]
    pub incoming: Option<OneOrMany>,
    /// この種類の関係(例: `derivation`)を 1 本以上出す。並びはいずれかでよい。
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "codegen", ts(optional))]
    pub outgoing: Option<OneOrMany>,
    /// 要素名がこの正規表現に当たる。
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "codegen", ts(optional))]
    pub name: Option<String>,
    /// `true` なら工程(`@Phase`)を持つ、`false` なら持たない。
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "codegen", ts(optional))]
    pub phase: Option<bool>,
    /// ポートの数。
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "codegen", ts(optional))]
    pub ports: Option<CountRange>,
    /// 同じ形の条件の否定(満たさないこと)。
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "codegen", ts(optional))]
    pub not: Option<Box<Requirement>>,
}

/// 数の範囲(両端を含む)。省いた側は制限しない。
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct CountRange {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "codegen", ts(optional))]
    pub min: Option<u32>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "codegen", ts(optional))]
    pub max: Option<u32>,
}

/// 文字列 1 つか、文字列の並び。
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
#[serde(untagged)]
pub enum OneOrMany {
    One(String),
    Many(Vec<String>),
}

impl OneOrMany {
    /// 並びとして見る(1 つなら長さ 1)。
    pub fn as_slice(&self) -> &[String] {
        match self {
            Self::One(s) => std::slice::from_ref(s),
            Self::Many(v) => v,
        }
    }
}

/// ルール ID(例: `req-has-satisfier`)。
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize)]
#[cfg_attr(feature = "codegen", derive(ts_rs::TS))]
#[cfg_attr(feature = "codegen", ts(type = "string"))]
pub struct RuleId(String);

impl<'de> Deserialize<'de> for RuleId {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        String::deserialize(d)?
            .try_into()
            .map_err(serde::de::Error::custom)
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RuleIdError(pub String);

impl fmt::Display for RuleIdError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "invalid rule id {:?}: expected lowercase letters, digits and '-' like \"req-has-satisfier\"",
            self.0
        )
    }
}

impl std::error::Error for RuleIdError {}

impl RuleId {
    pub fn as_str(&self) -> &str {
        &self.0
    }

    fn is_valid(s: &str) -> bool {
        let is_word = |c: char| c.is_ascii_lowercase() || c.is_ascii_digit();
        let mut chars = s.chars();
        chars.next().is_some_and(is_word) && chars.all(|c| is_word(c) || c == '-')
    }
}

impl TryFrom<String> for RuleId {
    type Error = RuleIdError;
    fn try_from(s: String) -> Result<Self, Self::Error> {
        if Self::is_valid(&s) {
            Ok(Self(s))
        } else {
            Err(RuleIdError(s))
        }
    }
}

impl std::str::FromStr for RuleId {
    type Err = RuleIdError;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        s.to_owned().try_into()
    }
}

impl From<RuleId> for String {
    fn from(id: RuleId) -> Self {
        id.0
    }
}

impl fmt::Display for RuleId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.0)
    }
}

#[cfg(feature = "codegen")]
impl schemars::JsonSchema for RuleId {
    fn schema_name() -> std::borrow::Cow<'static, str> {
        "RuleId".into()
    }

    fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
        schemars::json_schema!({
            "type": "string",
            "pattern": RULE_ID_PATTERN,
            "description": "Rule id unique within the plugin, e.g. \"req-has-satisfier\"."
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn rule_with(require: &str) -> String {
        format!(
            r#"{{"rules":[{{"id":"r","severity":"warning","message":"m","match":{{"kind":"part def"}},"require":{require}}}]}}"#
        )
    }

    fn parse(json: &str) -> Result<RuleSet, serde_json::Error> {
        serde_json::from_str(json)
    }

    // --- 正常系 ---

    #[test]
    fn parses_full_rule() {
        // Arrange
        let json = r#"{"rules":[{
            "id": "req-has-satisfier",
            "severity": "warning",
            "message": "要求「{name}」を満たす部品がありません",
            "match": { "kind": "requirement def", "phase": "SystemRequirements", "name": "^[A-Z]" },
            "require": { "incoming": "satisfy" }
        }]}"#;
        // Act
        let set = parse(json).unwrap();
        // Assert
        assert_eq!(
            set.rules,
            vec![Rule {
                id: "req-has-satisfier".parse().unwrap(),
                severity: DiagnosticSeverity::Warning,
                message: "要求「{name}」を満たす部品がありません".to_owned(),
                target: ElementMatch {
                    kind: OneOrMany::One("requirement def".to_owned()),
                    phase: Some("SystemRequirements".to_owned()),
                    name: Some("^[A-Z]".to_owned()),
                },
                require: Requirement {
                    incoming: Some(OneOrMany::One("satisfy".to_owned())),
                    ..Requirement::default()
                },
            }]
        );
    }

    #[test]
    fn one_or_many_accepts_string_and_list() {
        // Arrange(同値クラス: 文字列 1 つ/並び)
        let inputs = [r#""a""#, r#"["a","b"]"#];
        // Act
        let slices: Vec<Vec<String>> = inputs
            .iter()
            .map(|s| {
                serde_json::from_str::<OneOrMany>(s)
                    .unwrap()
                    .as_slice()
                    .to_vec()
            })
            .collect();
        // Assert
        assert_eq!(slices, [vec!["a"], vec!["a", "b"]]);
    }

    #[test]
    fn parses_every_require_field_and_nested_not() {
        // Arrange
        let json = rule_with(
            r#"{"outgoing":["derivation","flow"],"name":"^[A-Z]\\w*$","phase":true,
                "ports":{"min":1,"max":8},"not":{"incoming":"satisfy"}}"#,
        );
        // Act
        let require = parse(&json).unwrap().rules.remove(0).require;
        // Assert
        assert_eq!(
            require,
            Requirement {
                incoming: None,
                outgoing: Some(OneOrMany::Many(vec![
                    "derivation".to_owned(),
                    "flow".to_owned()
                ])),
                name: Some(r"^[A-Z]\w*$".to_owned()),
                phase: Some(true),
                ports: Some(CountRange {
                    min: Some(1),
                    max: Some(8)
                }),
                not: Some(Box::new(Requirement {
                    incoming: Some(OneOrMany::One("satisfy".to_owned())),
                    ..Requirement::default()
                })),
            }
        );
    }

    #[test]
    fn accepts_empty_rule_list() {
        // Arrange(境界値: ルール 0 件)
        let json = r#"{"rules":[]}"#;
        // Act
        let set = parse(json).unwrap();
        // Assert
        assert!(set.rules.is_empty());
    }

    #[test]
    fn accepts_rule_ids_at_the_edges() {
        // Arrange(境界値: 1 文字・数字始まり・末尾の `-`)
        let ids = ["a", "0", "a-", "req-2"];
        // Act
        let results: Vec<bool> = ids.iter().map(|id| id.parse::<RuleId>().is_ok()).collect();
        // Assert
        assert_eq!(results, [true, true, true, true]);
    }

    // --- 異常系 ---

    #[test]
    fn rejects_malformed_rule_ids() {
        // Arrange(空・`-` 始まり・大文字・使えない文字)
        let ids = ["", "-a", "Req", "req_x", "req.x", "要求"];
        // Act
        let accepted: Vec<&str> = ids
            .iter()
            .copied()
            .filter(|id| id.parse::<RuleId>().is_ok())
            .collect();
        // Assert
        assert!(accepted.is_empty(), "accepted: {accepted:?}");
    }

    #[test]
    fn rejects_unknown_keys_at_every_level() {
        // Arrange(ルールセット・ルール・match・require・ports・not の各階層)
        let cases = [
            r#"{"rules":[],"extra":1}"#.to_owned(),
            r#"{"rules":[{"id":"r","severity":"hint","message":"m","match":{"kind":"x"},"require":{},"extra":1}]}"#.to_owned(),
            r#"{"rules":[{"id":"r","severity":"hint","message":"m","match":{"kind":"x","extra":1},"require":{}}]}"#.to_owned(),
            rule_with(r#"{"extra":1}"#),
            rule_with(r#"{"ports":{"min":1,"extra":1}}"#),
            rule_with(r#"{"not":{"extra":1}}"#),
        ];
        // Act
        let accepted: Vec<&String> = cases.iter().filter(|c| parse(c).is_ok()).collect();
        // Assert
        assert!(accepted.is_empty(), "accepted: {accepted:?}");
    }

    #[test]
    fn rejects_missing_match_kind() {
        // Arrange(必須の `kind` が欠ける)
        let json = r#"{"rules":[{"id":"r","severity":"hint","message":"m","match":{"phase":"P"},"require":{}}]}"#;
        // Act
        let result = parse(json);
        // Assert
        assert!(result.is_err());
    }

    #[test]
    fn rejects_unknown_severity() {
        // Arrange
        let json = r#"{"rules":[{"id":"r","severity":"fatal","message":"m","match":{"kind":"x"},"require":{}}]}"#;
        // Act
        let result = parse(json);
        // Assert
        assert!(result.is_err());
    }

    #[test]
    fn rejects_negative_port_count() {
        // Arrange(境界値: min = -1)
        let json = rule_with(r#"{"ports":{"min":-1}}"#);
        // Act
        let result = parse(&json);
        // Assert
        assert!(result.is_err());
    }

    #[test]
    fn rejects_kind_that_is_neither_string_nor_list() {
        // Arrange(異常系: 数値・文字列以外を含む並び)
        let inputs = ["1", r#"["a",1]"#];
        // Act
        let accepted: Vec<&str> = inputs
            .iter()
            .copied()
            .filter(|s| serde_json::from_str::<OneOrMany>(s).is_ok())
            .collect();
        // Assert
        assert!(accepted.is_empty(), "accepted: {accepted:?}");
    }
}