panache_parser/parser/yaml/
profile.rs

1//! Consumer profiles for YAML validation.
2//!
3//! Panache's YAML structural validator (`super::validator`) mirrors abstract
4//! **YAML 1.2** — the contract the vendored yaml-test-suite holds it to. But
5//! the *real* consumers of the YAML in a document are stricter and differ by
6//! context:
7//!
8//! - **Frontmatter** is read by **pandoc** → Haskell `yaml`/libyaml (≈ 1.1).
9//! - **Hashpipe `#|` cell options** are read by **quarto** → js-yaml (1.2).
10//! - In a **Quarto** doc, quarto parses the frontmatter (js-yaml) *and* hands
11//!   the document to pandoc, which re-parses the metadata (libyaml). So Quarto
12//!   frontmatter must satisfy **both** — the stricter wins.
13//!
14//! A [`YamlValidationContext`] captures which real consumers apply to a given
15//! (flavor, location), so the validator can layer consumer-only checks on top
16//! of the 1.2 substrate. The empirical basis for each consumer's accept/reject
17//! behavior is the oracle audit in `scripts/yaml-oracle/` and its classified
18//! output in `crates/panache-parser/tests/yaml/consumer-matrix.md`.
19//!
20//! The substrate path ([`YamlValidationContext::substrate`]) runs every 1.2
21//! check and **no** consumer-only checks — it is what the yaml-test-suite tests
22//! exercise, so its verdicts never change.
23
24use crate::options::Flavor;
25
26/// A real-world YAML parser whose accept/reject behavior Panache mirrors. These
27/// are distinct measured consumers, not interchangeable libyaml wrappers — see
28/// `scripts/yaml-oracle/oracle.json` and `tests/yaml/consumer-matrix.md`.
29#[derive(Debug, Clone, Copy, PartialEq, Eq)]
30pub enum YamlConsumer {
31    /// pandoc's Haskell `yaml` (libyaml, ≈ YAML 1.1). Reads frontmatter. The
32    /// lenient baseline: accepts duplicate keys (last value wins) and tabs in
33    /// some positions.
34    Libyaml,
35    /// js-yaml (YAML 1.2). Reads Quarto frontmatter and hashpipe `#|` options.
36    /// Rejects duplicate keys and tabs.
37    Jsyaml,
38    /// R's `yaml` package (libyaml-based), used by the RMarkdown toolchain —
39    /// `rmarkdown::yaml_front_matter` for frontmatter and knitr for `#|` chunk
40    /// options. Like libyaml but, measured against the suite, additionally
41    /// REJECTS duplicate keys and tabs.
42    RYaml,
43}
44
45/// A small bitset over [`YamlConsumer`].
46#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
47pub struct ConsumerSet(u8);
48
49impl ConsumerSet {
50    const fn bit(consumer: YamlConsumer) -> u8 {
51        match consumer {
52            YamlConsumer::Libyaml => 0b001,
53            YamlConsumer::Jsyaml => 0b010,
54            YamlConsumer::RYaml => 0b100,
55        }
56    }
57
58    /// Every consumer — the rejection set for a check all real parsers make.
59    pub const fn all() -> Self {
60        ConsumerSet(0b111)
61    }
62
63    /// The empty set — no real consumer applies (lenient).
64    pub const fn empty() -> Self {
65        ConsumerSet(0)
66    }
67
68    /// A single-consumer set.
69    pub const fn of(consumer: YamlConsumer) -> Self {
70        ConsumerSet(Self::bit(consumer))
71    }
72
73    /// Add a consumer.
74    pub const fn with(self, consumer: YamlConsumer) -> Self {
75        ConsumerSet(self.0 | Self::bit(consumer))
76    }
77
78    /// Does this set contain `consumer`?
79    pub const fn contains(self, consumer: YamlConsumer) -> bool {
80        self.0 & Self::bit(consumer) != 0
81    }
82
83    /// Do the two sets share any consumer?
84    pub const fn intersects(self, other: ConsumerSet) -> bool {
85        self.0 & other.0 != 0
86    }
87
88    /// Is this set empty?
89    pub const fn is_empty(self) -> bool {
90        self.0 == 0
91    }
92}
93
94/// Where in a document the YAML lives. Frontmatter is read by pandoc (and, in
95/// Quarto, also js-yaml); hashpipe `#|` cell options are read by the executable
96/// engine (js-yaml for Quarto, the R `yaml` package for RMarkdown).
97#[derive(Debug, Clone, Copy, PartialEq, Eq)]
98pub enum YamlLocation {
99    Frontmatter,
100    Hashpipe,
101}
102
103/// The consumers that must accept a YAML region, derived from (flavor,
104/// location). Validation rejects a region iff **any** active consumer rejects
105/// it.
106#[derive(Debug, Clone, Copy, PartialEq, Eq)]
107pub struct YamlValidationContext {
108    consumers: ConsumerSet,
109    substrate: bool,
110}
111
112impl YamlValidationContext {
113    /// The abstract YAML-1.2 substrate: run every 1.2 check and no consumer-only
114    /// checks. This is the contract the yaml-test-suite holds the validator to,
115    /// so its verdicts are independent of any flavor/location.
116    pub const fn substrate() -> Self {
117        Self {
118            consumers: ConsumerSet::empty(),
119            substrate: true,
120        }
121    }
122
123    /// Build a production context for a (flavor, location).
124    pub fn new(flavor: Flavor, location: YamlLocation) -> Self {
125        let consumers = match location {
126            YamlLocation::Frontmatter => frontmatter_consumers(flavor),
127            YamlLocation::Hashpipe => hashpipe_consumers(flavor),
128        };
129        Self {
130            consumers,
131            substrate: false,
132        }
133    }
134
135    /// Convenience: a frontmatter context for `flavor`.
136    pub fn frontmatter(flavor: Flavor) -> Self {
137        Self::new(flavor, YamlLocation::Frontmatter)
138    }
139
140    /// Convenience: a hashpipe `#|` context for `flavor`.
141    pub fn hashpipe(flavor: Flavor) -> Self {
142        Self::new(flavor, YamlLocation::Hashpipe)
143    }
144
145    /// True for the 1.2 substrate path (suite tests). Consumer-only checks must
146    /// never run here.
147    pub const fn is_substrate(&self) -> bool {
148        self.substrate
149    }
150
151    /// The active consumer set.
152    pub const fn consumers(&self) -> ConsumerSet {
153        self.consumers
154    }
155
156    /// True when at least one active consumer is among `rejecting` — i.e. a
157    /// consumer-only check whose rejection set is `rejecting` should fire.
158    pub const fn any_rejects(&self, rejecting: ConsumerSet) -> bool {
159        self.consumers.intersects(rejecting)
160    }
161}
162
163/// Frontmatter consumers by flavor:
164/// - Pandoc: pandoc/libyaml only.
165/// - Quarto: quarto parses the frontmatter (js-yaml) and then hands the doc to
166///   pandoc (libyaml), so both must accept.
167/// - RMarkdown: `rmarkdown::yaml_front_matter` (R `yaml`) reads it, then the doc
168///   renders through pandoc (libyaml), so both must accept.
169/// - GFM/CommonMark/MultiMarkdown/Mdsvex/MyST: no asserted YAML metadata
170///   consumer — lenient. (MyST frontmatter is real YAML read by PyYAML, but the
171///   parse-first MyST flavor stays lenient until its loader is modeled.)
172///
173/// See `tests/yaml/consumer-matrix.md`.
174fn frontmatter_consumers(flavor: Flavor) -> ConsumerSet {
175    match flavor {
176        Flavor::Pandoc => ConsumerSet::of(YamlConsumer::Libyaml),
177        Flavor::Quarto => ConsumerSet::of(YamlConsumer::Libyaml).with(YamlConsumer::Jsyaml),
178        Flavor::RMarkdown => ConsumerSet::of(YamlConsumer::Libyaml).with(YamlConsumer::RYaml),
179        Flavor::Gfm
180        | Flavor::CommonMark
181        | Flavor::MultiMarkdown
182        | Flavor::Mdsvex
183        | Flavor::Myst => ConsumerSet::empty(),
184    }
185}
186
187/// Hashpipe `#|` cell options are parsed by the executable engine: js-yaml for
188/// Quarto, the R `yaml` package for RMarkdown (via knitr). Other flavors do not
189/// recognize executable cells, so no hashpipe region reaches validation there.
190fn hashpipe_consumers(flavor: Flavor) -> ConsumerSet {
191    match flavor {
192        Flavor::Quarto => ConsumerSet::of(YamlConsumer::Jsyaml),
193        Flavor::RMarkdown => ConsumerSet::of(YamlConsumer::RYaml),
194        Flavor::Pandoc
195        | Flavor::Gfm
196        | Flavor::CommonMark
197        | Flavor::MultiMarkdown
198        | Flavor::Mdsvex
199        | Flavor::Myst => ConsumerSet::empty(),
200    }
201}
202
203#[cfg(test)]
204mod tests {
205    use super::*;
206
207    #[test]
208    fn substrate_runs_no_consumer_checks() {
209        let ctx = YamlValidationContext::substrate();
210        assert!(ctx.is_substrate());
211        assert!(ctx.consumers().is_empty());
212    }
213
214    #[test]
215    fn pandoc_frontmatter_is_libyaml_only() {
216        let ctx = YamlValidationContext::frontmatter(Flavor::Pandoc);
217        assert!(!ctx.is_substrate());
218        assert!(ctx.consumers().contains(YamlConsumer::Libyaml));
219        assert!(!ctx.consumers().contains(YamlConsumer::Jsyaml));
220    }
221
222    #[test]
223    fn quarto_frontmatter_is_both() {
224        let ctx = YamlValidationContext::frontmatter(Flavor::Quarto);
225        assert!(ctx.consumers().contains(YamlConsumer::Libyaml));
226        assert!(ctx.consumers().contains(YamlConsumer::Jsyaml));
227    }
228
229    #[test]
230    fn quarto_hashpipe_is_jsyaml_only() {
231        let ctx = YamlValidationContext::hashpipe(Flavor::Quarto);
232        assert!(ctx.consumers().contains(YamlConsumer::Jsyaml));
233        assert!(!ctx.consumers().contains(YamlConsumer::Libyaml));
234    }
235
236    #[test]
237    fn rmarkdown_uses_pandoc_and_r_yaml() {
238        let fm = YamlValidationContext::frontmatter(Flavor::RMarkdown);
239        assert!(fm.consumers().contains(YamlConsumer::Libyaml)); // renders via pandoc
240        assert!(fm.consumers().contains(YamlConsumer::RYaml)); // rmarkdown::yaml_front_matter
241        assert!(!fm.consumers().contains(YamlConsumer::Jsyaml));
242
243        let hp = YamlValidationContext::hashpipe(Flavor::RMarkdown);
244        assert!(hp.consumers().contains(YamlConsumer::RYaml)); // knitr
245        assert!(!hp.consumers().contains(YamlConsumer::Jsyaml));
246        assert!(!hp.consumers().contains(YamlConsumer::Libyaml));
247    }
248
249    #[test]
250    fn commonmark_frontmatter_is_lenient() {
251        let ctx = YamlValidationContext::frontmatter(Flavor::CommonMark);
252        assert!(ctx.consumers().is_empty());
253        assert!(!ctx.is_substrate());
254    }
255
256    #[test]
257    fn any_rejects_matches_intersection() {
258        // implicit-empty-key rejects under every consumer.
259        let all = ConsumerSet::all();
260        assert!(YamlValidationContext::frontmatter(Flavor::Pandoc).any_rejects(all));
261        assert!(YamlValidationContext::frontmatter(Flavor::RMarkdown).any_rejects(all));
262
263        // duplicate-key rejects under js-yaml (Quarto) and R yaml (RMarkdown),
264        // not under pandoc/libyaml.
265        let dup = ConsumerSet::of(YamlConsumer::Jsyaml).with(YamlConsumer::RYaml);
266        assert!(!YamlValidationContext::frontmatter(Flavor::Pandoc).any_rejects(dup));
267        assert!(YamlValidationContext::frontmatter(Flavor::Quarto).any_rejects(dup));
268        assert!(YamlValidationContext::frontmatter(Flavor::RMarkdown).any_rejects(dup));
269        assert!(YamlValidationContext::hashpipe(Flavor::RMarkdown).any_rejects(dup));
270    }
271}
panache_parser/parser/yaml/profile.rs

panache_parser/parser/yaml/
profile.rs
