citum_engine/api/
forward_compat.rs

1/*
2SPDX-License-Identifier: MIT OR Apache-2.0
3SPDX-FileCopyrightText: © 2023-2026 Bruce D'Arcus
4*/
5
6//! Forward-compat unknown-field walking for `citum check`.
7//!
8//! Tolerant style option/section structs capture unknown keys into a
9//! `unknown_fields` map at parse time (see
10//! `docs/specs/FORWARD_COMPATIBILITY.md`). This module walks a parsed
11//! [`Style`] and reports every populated capture, so CLI surfaces such as
12//! `citum check --strict` can emit them as warnings or errors.
13
14use citum_schema::CitationSpec;
15use citum_schema::Style;
16use citum_schema::options::{
17    BibliographyOptions, CitationOptions, Config, LocatorConfig, SubstituteConfig,
18};
19
20/// A single populated `unknown_fields` capture located in a parsed [`Style`].
21#[derive(Debug, Clone, PartialEq, Eq)]
22pub struct UnknownFieldPath {
23    /// Dotted path to the struct that captured the keys.
24    pub path: String,
25    /// The unknown keys captured at that path.
26    pub keys: Vec<String>,
27}
28
29/// Walk a parsed [`Style`] and collect every populated `unknown_fields`
30/// capture (top-level, options, nested option structs, nested citation
31/// specs).
32#[must_use]
33pub fn collect_unknown_field_paths(style: &Style) -> Vec<UnknownFieldPath> {
34    let mut out = Vec::new();
35    push_keys(&mut out, "$", style.unknown_fields.keys());
36
37    if let Some(options) = &style.options {
38        walk_config(&mut out, "$.options", options);
39    }
40    if let Some(citation) = &style.citation {
41        walk_citation_spec(&mut out, "$.citation", citation);
42    }
43    if let Some(bib) = &style.bibliography {
44        push_keys(&mut out, "$.bibliography", bib.unknown_fields.keys());
45        if let Some(bo) = &bib.options {
46            push_keys(&mut out, "$.bibliography.options", bo.unknown_fields.keys());
47            walk_bibliography_options_nested(&mut out, "$.bibliography.options", bo);
48        }
49    }
50
51    out
52}
53
54fn walk_citation_spec(out: &mut Vec<UnknownFieldPath>, base: &str, spec: &CitationSpec) {
55    push_keys(out, base, spec.unknown_fields.keys());
56    if let Some(co) = &spec.options {
57        push_keys(out, &format!("{base}.options"), co.unknown_fields.keys());
58        walk_citation_options_nested(out, &format!("{base}.options"), co);
59    }
60    if let Some(child) = &spec.integral {
61        walk_citation_spec(out, &format!("{base}.integral"), child);
62    }
63    if let Some(child) = &spec.non_integral {
64        walk_citation_spec(out, &format!("{base}.non-integral"), child);
65    }
66    if let Some(child) = &spec.subsequent {
67        walk_citation_spec(out, &format!("{base}.subsequent"), child);
68    }
69    if let Some(child) = &spec.ibid {
70        walk_citation_spec(out, &format!("{base}.ibid"), child);
71    }
72}
73
74fn walk_config(out: &mut Vec<UnknownFieldPath>, base: &str, c: &Config) {
75    push_keys(out, base, c.unknown_fields.keys());
76    if let Some(contributors) = &c.contributors {
77        push_keys(
78            out,
79            &format!("{base}.contributors"),
80            contributors.unknown_fields.keys(),
81        );
82    }
83    if let Some(SubstituteConfig::Explicit(sub)) = &c.substitute {
84        push_keys(
85            out,
86            &format!("{base}.substitute"),
87            sub.unknown_fields.keys(),
88        );
89    }
90    if let Some(dates) = &c.dates {
91        push_keys(out, &format!("{base}.dates"), dates.unknown_fields.keys());
92    }
93    if let Some(titles) = &c.titles {
94        push_keys(out, &format!("{base}.titles"), titles.unknown_fields.keys());
95    }
96    if let Some(locators) = &c.locators {
97        walk_locator_config(out, &format!("{base}.locators"), locators);
98    }
99    if let Some(notes) = &c.notes {
100        push_keys(out, &format!("{base}.notes"), notes.unknown_fields.keys());
101    }
102    if let Some(integral) = &c.integral_names {
103        push_keys(
104            out,
105            &format!("{base}.integral-names"),
106            integral.unknown_fields.keys(),
107        );
108    }
109}
110
111fn walk_locator_config(out: &mut Vec<UnknownFieldPath>, base: &str, lc: &LocatorConfig) {
112    push_keys(out, base, lc.unknown_fields.keys());
113    for (kind, cfg) in &lc.kinds {
114        push_keys(
115            out,
116            &format!("{base}.kinds.{kind:?}"),
117            cfg.unknown_fields.keys(),
118        );
119    }
120    for (idx, pattern) in lc.patterns.iter().enumerate() {
121        push_keys(
122            out,
123            &format!("{base}.patterns[{idx}]"),
124            pattern.unknown_fields.keys(),
125        );
126    }
127}
128
129fn walk_citation_options_nested(out: &mut Vec<UnknownFieldPath>, base: &str, co: &CitationOptions) {
130    if let Some(contributors) = &co.contributors {
131        push_keys(
132            out,
133            &format!("{base}.contributors"),
134            contributors.unknown_fields.keys(),
135        );
136    }
137    if let Some(dates) = &co.dates {
138        push_keys(out, &format!("{base}.dates"), dates.unknown_fields.keys());
139    }
140    if let Some(titles) = &co.titles {
141        push_keys(out, &format!("{base}.titles"), titles.unknown_fields.keys());
142    }
143    if let Some(locators) = &co.locators {
144        walk_locator_config(out, &format!("{base}.locators"), locators);
145    }
146    if let Some(notes) = &co.notes {
147        push_keys(out, &format!("{base}.notes"), notes.unknown_fields.keys());
148    }
149    if let Some(integral) = &co.integral_names {
150        push_keys(
151            out,
152            &format!("{base}.integral-names"),
153            integral.unknown_fields.keys(),
154        );
155    }
156}
157
158fn walk_bibliography_options_nested(
159    out: &mut Vec<UnknownFieldPath>,
160    base: &str,
161    bo: &BibliographyOptions,
162) {
163    if let Some(contributors) = &bo.contributors {
164        push_keys(
165            out,
166            &format!("{base}.contributors"),
167            contributors.unknown_fields.keys(),
168        );
169    }
170    if let Some(dates) = &bo.dates {
171        push_keys(out, &format!("{base}.dates"), dates.unknown_fields.keys());
172    }
173    if let Some(titles) = &bo.titles {
174        push_keys(out, &format!("{base}.titles"), titles.unknown_fields.keys());
175    }
176    if let Some(article_journal) = &bo.article_journal {
177        push_keys(
178            out,
179            &format!("{base}.article-journal"),
180            article_journal.unknown_fields.keys(),
181        );
182    }
183    if let Some(compound) = &bo.compound_numeric {
184        push_keys(
185            out,
186            &format!("{base}.compound-numeric"),
187            compound.unknown_fields.keys(),
188        );
189    }
190    if let Some(partitioning) = &bo.sort_partitioning {
191        push_keys(
192            out,
193            &format!("{base}.sort-partitioning"),
194            partitioning.unknown_fields.keys(),
195        );
196    }
197}
198
199fn push_keys<'a, I>(out: &mut Vec<UnknownFieldPath>, path: &str, keys: I)
200where
201    I: IntoIterator<Item = &'a String>,
202{
203    let collected: Vec<String> = keys.into_iter().cloned().collect();
204    if !collected.is_empty() {
205        out.push(UnknownFieldPath {
206            path: path.to_string(),
207            keys: collected,
208        });
209    }
210}
citum_engine/api/forward_compat.rs

citum_engine/api/
forward_compat.rs
