provenant/license_detection/models/
rule.rs

1//! Rule metadata loaded from .LICENSE and .RULE files.
2
3use std::collections::HashMap;
4use std::ops::Range;
5
6use serde::{Deserialize, Serialize};
7
8use crate::license_detection::index::dictionary::TokenId;
9
10const SCANCODE_LICENSE_URL_BASE: &str =
11    "https://github.com/nexB/scancode-toolkit/tree/develop/src/licensedcode/data/licenses";
12const SCANCODE_RULE_URL_BASE: &str =
13    "https://github.com/nexB/scancode-toolkit/tree/develop/src/licensedcode/data/rules";
14
15mod range_serde {
16    use serde::{Deserialize, Deserializer, Serialize, Serializer};
17    use std::ops::Range;
18
19    pub fn serialize<S>(ranges: &[Range<usize>], serializer: S) -> Result<S::Ok, S::Error>
20    where
21        S: Serializer,
22    {
23        let tuples: Vec<(usize, usize)> = ranges.iter().map(|r| (r.start, r.end)).collect();
24        tuples.serialize(serializer)
25    }
26
27    pub fn deserialize<'de, D>(deserializer: D) -> Result<Vec<Range<usize>>, D::Error>
28    where
29        D: Deserializer<'de>,
30    {
31        let tuples: Vec<(usize, usize)> = Vec::deserialize(deserializer)?;
32        Ok(tuples
33            .into_iter()
34            .map(|(start, end)| Range { start, end })
35            .collect())
36    }
37}
38
39mod stopwords_serde {
40    use serde::{Deserialize, Deserializer, Serialize, Serializer};
41    use std::collections::HashMap;
42
43    pub fn serialize<S>(map: &HashMap<usize, usize>, serializer: S) -> Result<S::Ok, S::Error>
44    where
45        S: Serializer,
46    {
47        let mut entries: Vec<(usize, usize)> = map.iter().map(|(k, v)| (*k, *v)).collect();
48        entries.sort_by_key(|(k, _)| *k);
49        entries.serialize(serializer)
50    }
51
52    pub fn deserialize<'de, D>(deserializer: D) -> Result<HashMap<usize, usize>, D::Error>
53    where
54        D: Deserializer<'de>,
55    {
56        let entries: Vec<(usize, usize)> = Vec::deserialize(deserializer)?;
57        Ok(entries.into_iter().collect())
58    }
59}
60
61#[derive(
62    Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Default, Serialize, Deserialize,
63)]
64pub enum RuleKind {
65    #[default]
66    None,
67    Text,
68    Notice,
69    Reference,
70    Tag,
71    Intro,
72    Clue,
73}
74
75impl RuleKind {
76    pub fn from_rule_flags(
77        is_license_text: bool,
78        is_license_notice: bool,
79        is_license_reference: bool,
80        is_license_tag: bool,
81        is_license_intro: bool,
82        is_license_clue: bool,
83    ) -> Result<Self, &'static str> {
84        let mut active = None;
85
86        for (enabled, kind) in [
87            (is_license_text, Self::Text),
88            (is_license_notice, Self::Notice),
89            (is_license_reference, Self::Reference),
90            (is_license_tag, Self::Tag),
91            (is_license_intro, Self::Intro),
92            (is_license_clue, Self::Clue),
93        ] {
94            if !enabled {
95                continue;
96            }
97
98            if active.replace(kind).is_some() {
99                return Err("rule has multiple rule kinds set");
100            }
101        }
102
103        Ok(active.unwrap_or(Self::None))
104    }
105
106    pub const fn is_license_text(self) -> bool {
107        matches!(self, Self::Text)
108    }
109
110    pub const fn is_license_notice(self) -> bool {
111        matches!(self, Self::Notice)
112    }
113
114    pub const fn is_license_reference(self) -> bool {
115        matches!(self, Self::Reference)
116    }
117
118    pub const fn is_license_tag(self) -> bool {
119        matches!(self, Self::Tag)
120    }
121
122    pub const fn is_license_intro(self) -> bool {
123        matches!(self, Self::Intro)
124    }
125
126    pub const fn is_license_clue(self) -> bool {
127        matches!(self, Self::Clue)
128    }
129}
130
131/// Rule metadata loaded from .LICENSE and .RULE files.
132#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
133pub struct Rule {
134    /// Unique identifier for this rule (e.g., "mit.LICENSE", "gpl-2.0_12.RULE")
135    /// Used for sorting to match Python's attr.s field order.
136    /// This is the primary sort key after rid (which is None at sort time in Python).
137    pub identifier: String,
138
139    /// License expression string using SPDX syntax and ScanCode license keys
140    pub license_expression: String,
141
142    /// Pattern text to match
143    pub text: String,
144
145    /// Token IDs for the text (assigned during indexing)
146    #[serde(
147        serialize_with = "serialize_token_ids",
148        deserialize_with = "deserialize_token_ids"
149    )]
150    pub tokens: Vec<TokenId>,
151
152    /// Classification of this rule.
153    pub rule_kind: RuleKind,
154
155    /// True if exact matches to this rule are false positives
156    pub is_false_positive: bool,
157
158    /// True if this rule text is a required phrase.
159    /// A required phrase is an essential section of the rule text which must be
160    /// present in the case of partial matches.
161    pub is_required_phrase: bool,
162
163    /// True if this rule was created from a license file (not a .RULE file)
164    pub is_from_license: bool,
165
166    /// Relevance score 0-100 (100 is most relevant)
167    pub relevance: u8,
168
169    /// Minimum match coverage percentage (0-100) if specified
170    pub minimum_coverage: Option<u8>,
171
172    /// True if minimum_coverage was explicitly stored in source frontmatter
173    pub has_stored_minimum_coverage: bool,
174
175    /// Tokens must appear in order if true
176    pub is_continuous: bool,
177
178    /// Token position spans for required phrases parsed from {{...}} markers.
179    /// Each span represents positions in the rule text that MUST be matched.
180    #[serde(with = "range_serde", default)]
181    pub required_phrase_spans: Vec<Range<usize>>,
182
183    /// Mapping from token position to count of stopwords at that position.
184    /// Used for required phrase validation.
185    #[serde(with = "stopwords_serde", default)]
186    pub stopwords_by_pos: HashMap<usize, usize>,
187
188    /// Filenames where this rule should be considered
189    pub referenced_filenames: Option<Vec<String>>,
190
191    /// URLs that should be ignored when found in this rule text
192    pub ignorable_urls: Option<Vec<String>>,
193
194    /// Emails that should be ignored when found in this rule text
195    pub ignorable_emails: Option<Vec<String>>,
196
197    /// Copyrights that should be ignored when found in this rule text
198    pub ignorable_copyrights: Option<Vec<String>>,
199
200    /// Holder names that should be ignored when found in this rule text
201    pub ignorable_holders: Option<Vec<String>>,
202
203    /// Author names that should be ignored when found in this rule text
204    pub ignorable_authors: Option<Vec<String>>,
205
206    /// Programming language for the rule if specified
207    pub language: Option<String>,
208
209    /// Free text notes
210    pub notes: Option<String>,
211
212    /// Count of unique token IDs in the rule (computed during indexing)
213    pub length_unique: usize,
214
215    /// Count of unique legalese token IDs (tokens with ID < len_legalese)
216    pub high_length_unique: usize,
217
218    /// Total count of legalese token occurrences (with duplicates)
219    pub high_length: usize,
220
221    /// Minimum matched length threshold (occurrences-based)
222    pub min_matched_length: usize,
223
224    /// Minimum high-value token matched length threshold (occurrences-based)
225    pub min_high_matched_length: usize,
226
227    /// Minimum matched length threshold (unique tokens)
228    pub min_matched_length_unique: usize,
229
230    /// Minimum high-value token matched length threshold (unique tokens)
231    pub min_high_matched_length_unique: usize,
232
233    /// True if rule length < SMALL_RULE (15 tokens)
234    pub is_small: bool,
235
236    /// True if rule length < TINY_RULE (6 tokens)
237    pub is_tiny: bool,
238
239    /// True if the rule's first token is "license", "licence", or "licensed"
240    pub starts_with_license: bool,
241
242    /// True if the rule's last token is "license", "licence", or "licensed"
243    pub ends_with_license: bool,
244
245    /// Whether this rule is deprecated
246    pub is_deprecated: bool,
247
248    /// SPDX license identifier if available
249    pub spdx_license_key: Option<String>,
250
251    /// Alternative SPDX license identifiers (aliases)
252    pub other_spdx_license_keys: Vec<String>,
253}
254
255fn serialize_token_ids<S>(token_ids: &[TokenId], serializer: S) -> Result<S::Ok, S::Error>
256where
257    S: serde::Serializer,
258{
259    let raw_ids: Vec<u16> = token_ids.iter().map(|id| id.raw()).collect();
260    <Vec<u16> as serde::Serialize>::serialize(&raw_ids, serializer)
261}
262
263fn deserialize_token_ids<'de, D>(deserializer: D) -> Result<Vec<TokenId>, D::Error>
264where
265    D: serde::Deserializer<'de>,
266{
267    let raw_ids: Vec<u16> = Vec::deserialize(deserializer)?;
268    Ok(raw_ids.into_iter().map(TokenId::new).collect())
269}
270
271impl PartialOrd for Rule {
272    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
273        Some(self.cmp(other))
274    }
275}
276
277impl Ord for Rule {
278    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
279        self.identifier.cmp(&other.identifier)
280    }
281}
282
283impl Rule {
284    pub fn rule_url(&self) -> Option<String> {
285        if self.is_from_license {
286            return (!self.license_expression.is_empty()).then(|| {
287                format!(
288                    "{SCANCODE_LICENSE_URL_BASE}/{}.LICENSE",
289                    self.license_expression
290                )
291            });
292        }
293
294        (!self.identifier.is_empty())
295            .then(|| format!("{SCANCODE_RULE_URL_BASE}/{}", self.identifier))
296    }
297
298    pub const fn kind(&self) -> RuleKind {
299        self.rule_kind
300    }
301
302    pub const fn is_license_text(&self) -> bool {
303        self.rule_kind.is_license_text()
304    }
305
306    /// Returns true if this rule is a license notice pattern.
307    ///
308    /// Note: This method is kept for API completeness and potential future use.
309    /// License matches cannot have `is_license_notice` - only rules can.
310    #[allow(dead_code)]
311    pub const fn is_license_notice(&self) -> bool {
312        self.rule_kind.is_license_notice()
313    }
314
315    pub const fn is_license_reference(&self) -> bool {
316        self.rule_kind.is_license_reference()
317    }
318
319    pub const fn is_license_tag(&self) -> bool {
320        self.rule_kind.is_license_tag()
321    }
322
323    /// Returns true if this rule is a license introduction pattern.
324    ///
325    /// Note: This method is kept for API completeness and potential future use.
326    #[allow(dead_code)]
327    pub const fn is_license_intro(&self) -> bool {
328        self.rule_kind.is_license_intro()
329    }
330
331    pub const fn is_license_clue(&self) -> bool {
332        self.rule_kind.is_license_clue()
333    }
334}
provenant/license_detection/models/rule.rs

provenant/license_detection/models/
rule.rs
