Skip to main content

fallow_types/
guard.rs

1//! Guard report contracts for pre-edit architecture guidance.
2
3/// Per-file guard report for one or more requested paths.
4#[derive(Debug, Clone, serde::Serialize)]
5#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
6pub struct GuardReport {
7    /// Reports in the same order as the requested files.
8    pub files: Vec<GuardFileReport>,
9}
10
11/// Guard information for a single project-root-relative path.
12#[derive(Debug, Clone, serde::Serialize)]
13#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
14pub struct GuardFileReport {
15    /// Project-root-relative path using forward slashes.
16    pub path: String,
17    /// Whether the path currently exists on disk.
18    pub exists: bool,
19    /// Boundary zone classification for this file, when any zone matches.
20    pub zone: Option<GuardZone>,
21    /// Boundary rules that apply to this file.
22    pub boundary: GuardBoundary,
23    /// Rule-pack policy rules in scope for this file.
24    pub policy_rules: Vec<GuardPolicyRule>,
25    /// Effective severities for rule families relevant to guard output.
26    pub severities: GuardSeverities,
27    /// Human-readable notes for unrestricted or degraded cases.
28    pub notes: Vec<String>,
29}
30
31/// Boundary zone matched by a guard target.
32#[derive(Debug, Clone, serde::Serialize)]
33#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
34pub struct GuardZone {
35    /// Zone name from the boundary configuration.
36    pub name: String,
37    /// Configured glob patterns that define the zone.
38    pub patterns: Vec<String>,
39}
40
41/// Boundary permissions and call restrictions for a guard target.
42#[derive(Debug, Clone, serde::Serialize)]
43#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
44pub struct GuardBoundary {
45    /// Whether boundary zones are configured at all.
46    pub configured: bool,
47    /// Whether boundary imports are unrestricted for this file.
48    pub unrestricted: bool,
49    /// Zones this file may import from.
50    pub allowed_zones: Vec<String>,
51    /// Zones this file may import from with type-only imports.
52    pub allowed_type_only_zones: Vec<String>,
53    /// Forbidden callee patterns for the file's zone.
54    pub forbidden_calls: Vec<String>,
55    /// Whether boundary coverage requires this file to belong to a zone.
56    pub coverage_required: bool,
57}
58
59/// Rule-pack policy rule that applies to a guard target.
60#[derive(Debug, Clone, serde::Serialize)]
61#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
62pub struct GuardPolicyRule {
63    /// Rule-pack name.
64    pub pack: String,
65    /// Rule id inside the pack.
66    pub rule_id: String,
67    /// Rule kind in kebab-case.
68    pub kind: String,
69    /// Matcher patterns for the rule, such as callees, import specifiers, or effects.
70    pub patterns: Vec<String>,
71    /// Imported names that a `banned-import` rule still allows from its patterns.
72    #[serde(default, skip_serializing_if = "Vec::is_empty")]
73    pub allowed_names: Vec<String>,
74    /// Producer locations permitted by a gdp-ts proof rule.
75    #[serde(default, skip_serializing_if = "Vec::is_empty")]
76    pub allowed_files: Vec<String>,
77    /// Exact proof labels restricted by a gdp-ts proof rule; empty means all.
78    #[serde(default, skip_serializing_if = "Vec::is_empty")]
79    pub proof_kinds: Vec<String>,
80    /// Optional rule-authored remediation message.
81    pub message: Option<String>,
82    /// Effective severity for this rule at the target path.
83    pub severity: String,
84    /// Scoped suppression token for this specific policy rule.
85    pub suppress_token: String,
86}
87
88/// Effective guard-relevant rule severities for a target path.
89#[derive(Debug, Clone, serde::Serialize)]
90#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
91pub struct GuardSeverities {
92    /// Effective severity of boundary-violation findings.
93    pub boundary_violation: String,
94    /// Effective severity of policy-violation findings.
95    pub policy_violation: String,
96}
97
98#[cfg(test)]
99mod tests {
100    use super::*;
101
102    #[test]
103    fn guard_file_report_serializes_expected_wire_shape() {
104        let report = GuardReport {
105            files: vec![GuardFileReport {
106                path: "src/domain/user.ts".to_string(),
107                exists: false,
108                zone: None,
109                boundary: GuardBoundary {
110                    configured: true,
111                    unrestricted: true,
112                    allowed_zones: vec![],
113                    allowed_type_only_zones: vec![],
114                    forbidden_calls: vec!["child_process.*".to_string()],
115                    coverage_required: true,
116                },
117                policy_rules: vec![GuardPolicyRule {
118                    pack: "team-policy".to_string(),
119                    rule_id: "pure-domain".to_string(),
120                    kind: "banned-effect".to_string(),
121                    patterns: vec!["network".to_string()],
122                    allowed_names: vec![],
123                    allowed_files: vec![],
124                    proof_kinds: vec![],
125                    message: Some("Inject effects via ports.".to_string()),
126                    severity: "warn".to_string(),
127                    suppress_token: "policy-violation:team-policy/pure-domain".to_string(),
128                }],
129                severities: GuardSeverities {
130                    boundary_violation: "error".to_string(),
131                    policy_violation: "warn".to_string(),
132                },
133                notes: vec!["Files outside every zone are unrestricted.".to_string()],
134            }],
135        };
136
137        let json = serde_json::to_value(report).unwrap();
138        let file = &json["files"][0];
139        assert_eq!(file["path"], "src/domain/user.ts");
140        assert_eq!(file["exists"], false);
141        assert!(file["zone"].is_null());
142        assert_eq!(file["boundary"]["allowed_zones"], serde_json::json!([]));
143        assert_eq!(
144            file["boundary"]["allowed_type_only_zones"],
145            serde_json::json!([])
146        );
147        assert_eq!(file["boundary"]["coverage_required"], true);
148        assert_eq!(file["policy_rules"][0]["rule_id"], "pure-domain");
149        assert_eq!(
150            file["policy_rules"][0]["suppress_token"],
151            "policy-violation:team-policy/pure-domain"
152        );
153        assert_eq!(file["severities"]["boundary_violation"], "error");
154    }
155}