govctl 0.19.0

Project governance CLI for RFC, ADR, and Work Item management
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

use serde::{Deserialize, Serialize};

use super::{ClauseStatus, ConformanceEntry, ProjectIndex, RfcPhase, RfcStatus};

/// Conformance Case metadata section `[govctl]`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConformanceMeta {
    pub id: String,
    pub title: String,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub tags: Vec<String>,
}

/// Versioned RFC Clause binding owned by a Conformance Case.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RequirementBinding {
    #[serde(rename = "ref")]
    pub clause_ref: String,
    pub version: String,
}

/// Project-owned scenario locator and its declared trace edges.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConformanceContent {
    pub path: String,
    pub selector: String,
    pub requirements: Vec<RequirementBinding>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub guards: Vec<String>,
}

/// Complete Conformance Case file structure.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConformanceSpec {
    pub govctl: ConformanceMeta,
    pub case: ConformanceContent,
}

/// Derived requirement applicability used by trace consumers.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum ConformanceApplicability {
    Stale,
    Provisional,
    Candidate,
    Current,
}

impl std::fmt::Display for ConformanceApplicability {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let value = match self {
            Self::Stale => "stale",
            Self::Provisional => "provisional",
            Self::Candidate => "candidate",
            Self::Current => "current",
        };
        formatter.write_str(value)
    }
}

/// A requirement binding enriched with its derived applicability.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct ConformanceTraceRequirement {
    #[serde(rename = "ref")]
    pub clause_ref: String,
    pub version: String,
    pub requirement_applicability: ConformanceApplicability,
}

/// A Conformance Case enriched with trace-query semantics.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct ConformanceTraceCase {
    pub id: String,
    pub title: String,
    pub tags: Vec<String>,
    pub path: String,
    pub selector: String,
    pub requirements: Vec<ConformanceTraceRequirement>,
    pub guards: Vec<String>,
    pub requirement_applicability: ConformanceApplicability,
}

/// Derive the trace-query projection for a Conformance Case.
pub fn derive_conformance_trace(
    entry: &ConformanceEntry,
    index: &ProjectIndex,
) -> ConformanceTraceCase {
    let mut requirements = entry
        .spec
        .case
        .requirements
        .iter()
        .map(|binding| ConformanceTraceRequirement {
            clause_ref: binding.clause_ref.clone(),
            version: binding.version.clone(),
            requirement_applicability: requirement_applicability(binding, index),
        })
        .collect::<Vec<_>>();
    requirements.sort_by(|left, right| {
        left.clause_ref
            .cmp(&right.clause_ref)
            .then_with(|| left.version.cmp(&right.version))
    });

    let mut tags = entry.meta().tags.clone();
    tags.sort();
    tags.dedup();
    let mut guards = entry.spec.case.guards.clone();
    guards.sort();
    guards.dedup();
    let requirement_applicability = requirements
        .iter()
        .map(|requirement| requirement.requirement_applicability)
        .min()
        .unwrap_or(ConformanceApplicability::Stale);

    ConformanceTraceCase {
        id: entry.meta().id.clone(),
        title: entry.meta().title.clone(),
        tags,
        path: entry.spec.case.path.clone(),
        selector: entry.spec.case.selector.clone(),
        requirements,
        guards,
        requirement_applicability,
    }
}

fn requirement_applicability(
    binding: &RequirementBinding,
    index: &ProjectIndex,
) -> ConformanceApplicability {
    let Some((rfc_id, clause_id)) = binding.clause_ref.split_once(':') else {
        return ConformanceApplicability::Stale;
    };
    let Some(rfc) = index.rfcs.iter().find(|entry| entry.rfc.rfc_id == rfc_id) else {
        return ConformanceApplicability::Stale;
    };
    let Some(clause) = rfc
        .clauses
        .iter()
        .find(|entry| entry.spec.clause_id == clause_id)
    else {
        return ConformanceApplicability::Stale;
    };
    if clause.spec.status != ClauseStatus::Active || binding.version != rfc.rfc.version {
        return ConformanceApplicability::Stale;
    }

    match (rfc.rfc.status, rfc.rfc.phase, clause.spec.since.is_some()) {
        (RfcStatus::Draft, _, _) => ConformanceApplicability::Provisional,
        (RfcStatus::Normative, RfcPhase::Spec, true) => ConformanceApplicability::Candidate,
        (RfcStatus::Normative, RfcPhase::Impl | RfcPhase::Test | RfcPhase::Stable, true) => {
            ConformanceApplicability::Current
        }
        _ => ConformanceApplicability::Stale,
    }
}