1use std::collections::{BTreeMap, BTreeSet, HashMap};
17use std::sync::{Arc, LazyLock};
18
19use serde_json::{Map, Value};
20
21use crate::attributes::{attributes_end, parse_attributes};
22use crate::js::{JS_DOT, JS_SPACES, blank, is_str, js_not_space, js_trim, js_value, num, truthy, utf16_less};
23use crate::pattern::Pattern;
24use crate::policy::{Policy, PolicyLayer};
25use crate::registry::{self, AttrSpec, BACKMATTER_KEYS, KindSpec, attr_spec, is_rule, keyword_names, registry};
26use crate::types::{
27 Attrs, Diagnostic, Document, Form, Identity, KeyOrder, Metadata, Node, Object, Parameter, Range, Severity, Span, TREE_FORMAT,
28};
29use crate::yaml::{load_csv, load_json, load_yaml};
30
31pub(crate) const MAX_NESTING: usize = 128;
33
34#[derive(Clone, Debug, Default)]
36pub struct ReadOptions {
37 pub fragment: bool,
39 pub uri: String,
41 pub host: Option<PolicyLayer>,
44}
45
46#[derive(Clone, Debug, PartialEq)]
48pub(crate) struct ProseRef {
49 pub(crate) source: String,
50 pub(crate) range: Option<Range>,
51}
52
53#[derive(Clone, Debug)]
55pub struct Reading {
56 pub document: Document,
57 pub diagnostics: Vec<Diagnostic>,
59 pub identities: Vec<Identity>,
61 pub parameters: Vec<Parameter>,
63 pub footnotes: BTreeMap<String, u32>,
65 pub comments: BTreeSet<u32>,
67 pub lines: Vec<String>,
69 pub front_range: Option<Range>,
71 pub back_range: Option<Range>,
75 pub policy: Option<Policy>,
78
79 identity_index: HashMap<String, usize>,
80 parameter_index: HashMap<String, usize>,
81 pub(crate) prose_order: Vec<ProseRef>,
82 source: Arc<str>,
84 line_starts: Vec<usize>,
85}
86
87impl Reading {
88 pub(crate) fn empty() -> Reading {
89 Reading {
90 document: Document::default(),
91 diagnostics: Vec::new(),
92 identities: Vec::new(),
93 parameters: Vec::new(),
94 footnotes: BTreeMap::new(),
95 comments: BTreeSet::new(),
96 lines: Vec::new(),
97 front_range: None,
98 back_range: None,
99 policy: None,
100 identity_index: HashMap::new(),
101 parameter_index: HashMap::new(),
102 prose_order: Vec::new(),
103 source: Arc::from(""),
104 line_starts: Vec::new(),
105 }
106 }
107
108 pub fn source(&self) -> &str {
110 &self.source
111 }
112
113 pub fn line_offset(&self, line: u32) -> usize {
115 let i = (line as usize).saturating_sub(1);
116 self.line_starts.get(i).copied().unwrap_or(self.source.len())
117 }
118
119 pub fn changes_text(&self) -> bool {
134 self.text(None).trim_end_matches('\n') != self.source.trim_end_matches('\n')
135 }
136
137 pub fn identity(&self, id: &str) -> Option<&Identity> {
139 self.identity_index.get(id).and_then(|&i| self.identities.get(i))
140 }
141
142 pub fn parameter(&self, name: &str) -> Option<&Parameter> {
144 self.parameter_index.get(name).and_then(|&i| self.parameters.get(i))
145 }
146
147 pub fn has_errors(&self) -> bool {
149 self.diagnostics.iter().any(Diagnostic::is_error)
150 }
151
152 pub(crate) fn add_identity(&mut self, id: Identity, replace: bool) {
153 if let Some(&i) = self.identity_index.get(&id.id) {
154 if replace {
155 self.identities[i] = id;
156 }
157 return;
158 }
159 self.identity_index.insert(id.id.clone(), self.identities.len());
160 self.identities.push(id);
161 }
162}
163
164pub(crate) struct Rx {
167 pub(crate) open: Pattern,
168 pub(crate) close: Pattern,
169 pub(crate) fence: Pattern,
170 pub(crate) math: Pattern,
171 pub(crate) keyword: Pattern,
172 pub(crate) because: Pattern,
173 pub(crate) alert: Pattern,
174 pub(crate) quote: Pattern,
175 pub(crate) item: Pattern,
176 pub(crate) item_start: Pattern,
177 pub(crate) heading: Pattern,
178 pub(crate) thematic: Pattern,
179 pub(crate) heading_attr: Pattern,
180 pub(crate) footnote_def: Pattern,
181 pub(crate) quote_start: Pattern,
182 pub(crate) directive: Pattern,
183 pub(crate) closer: Pattern,
184 pub(crate) html_block: Pattern,
185 pub(crate) html_tag_line: Pattern,
186 pub(crate) backmatter: Pattern,
187 pub(crate) yaml_comment: Pattern,
188 pub(crate) region_part: Pattern,
189 pub(crate) url: Pattern,
190 pub(crate) duration: Pattern,
191 pub(crate) decimal: Pattern,
192 pub(crate) html_literals: Vec<(Pattern, Pattern)>,
194}
195
196pub(crate) static RX: LazyLock<Rx> = LazyLock::new(|| {
197 let dot = JS_DOT;
198 let sp = JS_SPACES;
199 let ns = js_not_space();
200 let kw = keyword_names();
201 let p = |s: &str| Pattern::must(s);
202 Rx {
203 open: p(&format!(r"^(:{{2,}})([a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)?)({dot}*)$")),
204 close: p(r"^(:{3,})[ \t]*$"),
205 fence: p(&format!(r"^((?:[ \t]*>)*[ \t]*)(`{{3,}}|~{{3,}})({dot}*)$")),
206 math: p(r"^\$\$[ \t]*$"),
207 keyword: p(&format!(r"^(\*\*)?({kw})(?:\[([^\]{sp}]*)\])?(?: \(if ([^()\r\n]*)\))?:(\*\*)?[ \t]+({ns}{dot}*)$")),
208 because: p(&format!(r"^(\*\*)?BECAUSE:(\*\*)?[ \t]+({ns}{dot}*)$")),
209 alert: p(r"^ {0,3}>[ \t]?\[!([A-Za-z]+(?:[ \t]+[A-Za-z]+)?)\][ \t]*$"),
210 quote: p(&format!(r"^ {{0,3}}>[ \t]?({dot}*)$")),
211 item: p(&format!(r"^([ \t]*)([-*+]|[0-9]{{1,9}}[.)])([ \t]+)({dot}*)$")),
212 item_start: p(r"^ {0,3}(?:[-*+]|[0-9]{1,9}[.)])(?:[ \t]|$)"),
213 heading: p(r"^ {0,3}#{1,6}(?:[ \t]|$)"),
214 thematic: p(r"^ {0,3}(?:(?:-[ \t]*){3,}|(?:\*[ \t]*){3,}|(?:_[ \t]*){3,})$"),
215 heading_attr: p(&format!(r"^ {{0,3}}#{{1,6}}[ \t]{dot}*?[ \t](\{{[^{{}}]*\}})[ \t]*$")),
216 footnote_def: p(&format!(r"^ {{0,3}}\[\^([^\]{sp}]+)\]:(?:[ \t]|$)")),
217 quote_start: p(r"^ {0,3}>"),
218 directive: p(r"^:{2,}[a-z]"),
219 closer: p(r"^(?:[ \t]*>)*[ \t]*(`+|~+)[ \t]*$"),
220 html_block: p(&format!(
221 r"(?i)^ {{0,3}}</?(?:address|article|aside|base|basefont|blockquote|body|caption|center|col|colgroup|dd|details|dialog|dir|div|dl|dt|fieldset|figcaption|figure|footer|form|frame|frameset|h[1-6]|head|header|hr|html|iframe|legend|li|link|main|menu|menuitem|nav|noframes|ol|optgroup|option|p|param|search|section|summary|table|tbody|td|tfoot|th|thead|title|tr|track|ul)(?:[{sp}/>]|$)"
222 )),
223 html_tag_line: p(&format!(
224 r#"^ {{0,3}}(?:<[A-Za-z][A-Za-z0-9-]*(?:[{sp}]+[A-Za-z_:][\w.:-]*(?:[{sp}]*=[{sp}]*(?:[^{sp}"'=<>`]+|'[^']*'|"[^"]*"))?)*[{sp}]*/?>|</[A-Za-z][A-Za-z0-9-]*[{sp}]*>)[{sp}]*$"#
225 )),
226 backmatter: p(&format!(r"^(?:{}):(?:[ \t]|$)", BACKMATTER_KEYS.join("|"))),
227 yaml_comment: p(r"^[ \t]*#"),
228 region_part: p(r"^(?:0|1|0?\.[0-9]+|1\.0+)$"),
229 url: p(&format!(r"(?i)^https?://[^{sp}]+$")),
230 duration: p(r"^[0-9]+(?:ms|s|m|h|d|w)$"),
231 decimal: p(r"^[+-]?(?:[0-9]+\.?[0-9]*|\.[0-9]+)(?:[eE][+-]?[0-9]+)?$"),
232 html_literals: vec![
233 (p(&format!(r"(?i)^( {{0,3}}<(?:script|pre|style|textarea))(?:[{sp}>]|$)")), p(r"(?i)</(?:script|pre|style|textarea)>")),
234 (p(r"^( {0,3}<\?)"), p(r"\?>")),
235 (p(r"^( {0,3}<!\[CDATA\[)"), p(r"\]\]>")),
236 (p(r"^( {0,3}<![A-Za-z])"), p(r">")),
237 ],
238 }
239});
240
241fn indent_of(s: &str) -> usize {
243 let lead = s.len() - s.trim_start_matches([' ', '\t']).len();
244 lead + 3 * s[..lead].matches('\t').count()
245}
246
247#[derive(Clone, Debug)]
250struct Line {
251 text: String,
252 n: u32,
253}
254
255#[derive(Clone, Copy, Debug, PartialEq)]
256enum BodyKind {
257 Parsed,
258 Literal,
259 Structured,
260 Opaque,
261}
262
263#[derive(Clone, Copy, Debug)]
264struct CodeFence {
265 ch: u8,
266 length: usize,
267}
268
269#[derive(Clone, Copy, Debug, PartialEq)]
270enum Shape {
271 Line,
272 Item,
273 Quote,
274}
275
276#[derive(Clone, Copy, Debug, PartialEq)]
277enum UnitKind {
278 Rule,
279 Reason,
280 Alert,
281}
282
283struct Unit {
285 kind: UnitKind,
286 node: usize,
288 rule: Option<usize>,
290 lines: Vec<Line>,
291 original: Vec<Line>,
293 shape: Shape,
294 offset: usize,
295 blanks: Vec<Line>,
296 last: String,
298}
299
300struct Frame {
302 node: Option<Node>,
303 nodes: Vec<Node>,
304 fence: usize,
305 body: BodyKind,
306 format: String,
307 raw: Vec<Line>,
308 raw_code: Option<CodeFence>,
309 md: Vec<Line>,
310 code: Option<CodeFence>,
311 html_end: Option<usize>,
313 html_blank: bool,
315 math_end: u32,
316 unit: Option<Unit>,
317 last_rule: Option<usize>,
318 prev_blank: bool,
319 paragraph: bool,
320 prev_quote: bool,
321 in_list: bool,
322}
323
324impl Frame {
325 fn new(node: Option<Node>, colons: usize, body: BodyKind, format: &str) -> Frame {
326 Frame {
327 node,
328 nodes: Vec::new(),
329 fence: colons,
330 body,
331 format: format.to_string(),
332 raw: Vec::new(),
333 raw_code: None,
334 md: Vec::new(),
335 code: None,
336 html_end: None,
337 html_blank: false,
338 math_end: 0,
339 unit: None,
340 last_rule: None,
341 prev_blank: true,
342 paragraph: false,
343 prev_quote: false,
344 in_list: false,
345 }
346 }
347}
348
349#[derive(Clone, Copy, Default)]
350struct ScopeOptions {
351 directives: bool,
352 keywords: bool,
353 document: bool,
354}
355
356struct Reader {
357 r: Reading,
358 opts: ReadOptions,
359 front: Object,
360 front_order: KeyOrder,
361 back: Object,
362 aliases: BTreeSet<String>,
363 depth: usize,
364}
365
366pub fn read(text: &str, opts: &ReadOptions) -> Reading {
368 let mut reader = Reader {
369 r: Reading::empty(),
370 opts: opts.clone(),
371 front: Object::new(),
372 front_order: KeyOrder::default(),
373 back: Object::new(),
374 aliases: BTreeSet::new(),
375 depth: 0,
376 };
377 let body = text.strip_prefix('\u{feff}').unwrap_or(text);
378 reader.r.lines = split_lines(body);
379 let bom = text.len() - body.len();
380 reader.r.line_starts = line_starts(body).into_iter().map(|i| i + bom).collect();
381 reader.r.source = Arc::from(text);
382 reader.run()
383}
384
385fn line_starts(body: &str) -> Vec<usize> {
387 let mut starts = vec![0];
388 let b = body.as_bytes();
389 let mut i = 0;
390 while i < b.len() {
391 match b[i] {
392 b'\n' => starts.push(i + 1),
393 b'\r' => {
394 if i + 1 < b.len() && b[i + 1] == b'\n' {
395 i += 1;
396 }
397 starts.push(i + 1);
398 }
399 _ => {}
400 }
401 i += 1;
402 }
403 starts
404}
405
406#[derive(Clone, Debug, PartialEq)]
408pub struct SplitBackmatter<'a> {
409 pub before: &'a str,
412 pub backmatter: Option<&'a str>,
414 pub range: Option<Range>,
416 pub data: Object,
418 pub diagnostics: Vec<Diagnostic>,
420}
421
422pub fn split_backmatter(text: &str) -> SplitBackmatter<'_> {
436 let r = read(text, &ReadOptions::default());
437 let Some(range) = r.back_range else {
438 return SplitBackmatter { before: text, backmatter: None, range: None, data: Object::new(), diagnostics: Vec::new() };
439 };
440 let cut = r.line_offset(range.start).min(text.len());
441 let (before, backmatter) = if text.is_char_boundary(cut) { text.split_at(cut) } else { (text, "") };
442 let diagnostics =
443 r.diagnostics.iter().filter(|d| d.code == "invalid-metadata" && d.line().is_some_and(|l| l >= range.start)).cloned().collect();
444 SplitBackmatter { before, backmatter: Some(backmatter), range: Some(range), data: r.document.metadata.back, diagnostics }
445}
446
447pub(crate) fn split_lines(body: &str) -> Vec<String> {
449 let mut lines = Vec::new();
450 let b = body.as_bytes();
451 let mut start = 0;
452 let mut i = 0;
453 while i < b.len() {
454 match b[i] {
455 b'\n' => {
456 lines.push(body[start..i].to_string());
457 start = i + 1;
458 }
459 b'\r' => {
460 lines.push(body[start..i].to_string());
461 if i + 1 < b.len() && b[i + 1] == b'\n' {
462 i += 1;
463 }
464 start = i + 1;
465 }
466 _ => {}
467 }
468 i += 1;
469 }
470 if start < b.len() {
471 lines.push(body[start..].to_string());
472 }
473 lines
474}
475
476pub(crate) fn sort_diagnostics(ds: &mut [Diagnostic], by_uri: bool) {
478 let start = |d: &Diagnostic| d.range.map_or(0, |r| r.start);
479 ds.sort_by(|a, b| {
480 if by_uri && a.uri != b.uri {
481 return if utf16_less(&a.uri, &b.uri) { std::cmp::Ordering::Less } else { std::cmp::Ordering::Greater };
482 }
483 start(a).cmp(&start(b)).then_with(|| a.code.cmp(b.code))
484 });
485}
486
487impl Reader {
488 fn diag(&mut self, code: &'static str, severity: Severity, message: impl Into<String>, line: u32) {
489 self.r.diagnostics.push(Diagnostic::new(code, severity, message, line));
490 }
491
492 fn run(mut self) -> Reading {
493 let mut first = 0;
494 if !self.opts.fragment && self.r.lines.first().is_some_and(|l| l == "---") {
495 let close = self.r.lines.iter().skip(1).position(|l| l == "---").map(|p| p + 1);
496 match close {
497 None => {
498 self.diag("invalid-metadata", Severity::Error, "the front matter is not closed: it ends with a line of exactly ---", 1)
499 }
500 Some(close) => {
501 self.r.front_range = Some(Range::new(1, close as u32 + 1));
502 let text = self.r.lines[1..close].join("\n");
503 let (front, order) = self.metadata(&text, 2, "front matter");
504 self.front = front;
505 self.front_order = order;
506 first = close + 1;
507 }
508 }
509 }
510 self.check_front();
511 let lines: Vec<Line> =
512 self.r.lines[first..].iter().enumerate().map(|(i, t)| Line { text: t.clone(), n: (first + i + 1) as u32 }).collect();
513 let body = self.scope(&lines, ScopeOptions { directives: true, keywords: true, document: !self.opts.fragment });
514 self.check_parameters();
515 if !self.opts.fragment {
516 let at = self.r.front_range.map_or(1, |r| r.start);
517 self.r.policy =
518 crate::policy::check(&self.front, &self.front_order, at, self.opts.host.as_ref(), &body, &mut self.r.diagnostics);
519 self.check_servers(&body);
520 }
521 let front = std::mem::take(&mut self.front);
522 let back = std::mem::take(&mut self.back);
523 self.r.document = Document {
524 format: TREE_FORMAT.into(),
525 uri: self.opts.uri.clone(),
526 metadata: Metadata { front, back, front_order: std::mem::take(&mut self.front_order) },
527 body,
528 raw: None,
529 };
530 sort_diagnostics(&mut self.r.diagnostics, false);
531 self.r
532 }
533
534 fn check_servers(&mut self, body: &[Node]) {
539 let inherits = self.front.contains_key("extends");
540 let mut out = Vec::new();
541 crate::objects::walk(body, &mut |n, _| {
542 let server = if n.kind == "tool" { n.attr_str("server").map_or("", str::trim) } else { "" };
543 if server.len() > 1 && server.starts_with('#') && !server.contains('/') {
544 let id = &server[1..];
545 let at = if n.form == Some(Form::Leaf) { "::tool" } else { ":::tool" };
546 let line = n.range.map_or(0, |r| r.start);
547 let d = match self.r.identity(id) {
548 None if inherits => None,
549 None => Some(Diagnostic::new(
550 "reference-optional",
551 Severity::Warning,
552 format!("{at}: server=#{id} names nothing in this document"),
553 line,
554 )),
555 Some(found) if found.kind == "mcp" || found.kind == "service" => None,
556 Some(found) => {
557 let article = if found.kind.starts_with(['a', 'e', 'i', 'o', 'u']) { "an" } else { "a" };
558 Some(Diagnostic::new(
559 "reference-kind",
560 Severity::Error,
561 format!("{at}: server=#{id} is {article} {}, not an mcp or a service", found.kind),
562 line,
563 ))
564 }
565 };
566 if let Some(mut d) = d {
567 if let Some(own) = n.attr_str("id") {
568 d.target = format!("#{own}");
569 }
570 out.push(d);
571 }
572 }
573 true
574 });
575 self.r.diagnostics.extend(out);
576 }
577
578 fn metadata(&mut self, yaml: &str, at: u32, what: &str) -> (Object, KeyOrder) {
580 match load_yaml(yaml) {
581 Err(e) => {
582 self.diag("invalid-metadata", Severity::Error, format!("the {what} is not valid YAML: {e}"), at);
583 (Object::new(), KeyOrder::default())
584 }
585 Ok((Value::Object(m), order)) => (m, order),
586 Ok(_) => {
587 self.diag("invalid-metadata", Severity::Error, format!("the {what} must be a YAML mapping"), at);
588 (Object::new(), KeyOrder::default())
589 }
590 }
591 }
592
593 fn scope(&mut self, lines: &[Line], o: ScopeOptions) -> Vec<Node> {
596 self.depth += 1;
597 let o = if self.depth > MAX_NESTING { ScopeOptions { keywords: false, ..o } } else { o };
599 let mut stack: Vec<Frame> = vec![Frame::new(None, usize::MAX, BodyKind::Parsed, "markdown")];
600 let mut comment_open = false;
601 let mut comment_line = 0;
602 let rx = &*RX;
603 let mut li = 0;
604 while li < lines.len() {
605 let ln = &lines[li];
606 li += 1;
607 let top_body = stack.last().map_or(BodyKind::Parsed, |f| f.body);
608 if top_body != BodyKind::Parsed {
609 self.raw_line(&mut stack, ln);
610 continue;
611 }
612 let Some(top) = stack.last_mut() else { break };
613 if let Some(code) = top.code {
614 literal_line(top, ln);
615 if closes_fence(&ln.text, code) {
616 top.code = None;
617 }
618 continue;
619 }
620 if let Some(end) = top.html_end {
621 literal_line(top, ln);
622 if rx.html_literals[end].1.is_match(&ln.text) {
623 top.html_end = None;
624 }
625 continue;
626 }
627 if top.math_end > 0 {
628 literal_line(top, ln);
629 if ln.n == top.math_end {
630 top.math_end = 0;
631 }
632 continue;
633 }
634
635 let mut cur = ln.clone();
637 if comment_open || ln.text.contains("<!--") {
638 let stripped = strip_comments(&ln.text, comment_open);
639 if stripped.opened && !comment_open {
640 comment_line = ln.n;
641 }
642 comment_open = stripped.still_open;
643 if stripped.only {
644 self.r.comments.insert(ln.n);
645 continue;
646 }
647 cur.text = stripped.text;
648 }
649
650 let depth = stack.len();
651 let top = stack.last_mut().expect("the root frame");
652 if top.html_blank {
653 if blank(&cur.text) {
654 top.html_blank = false;
655 } else {
656 literal_line(top, &cur);
657 continue;
658 }
659 }
660 if top.unit.is_some() {
661 if self.continue_unit(top, &cur) {
662 continue;
663 }
664 self.end_unit(top);
665 }
666 if o.document && depth == 1 && cur.text == "---" && top.prev_blank && li > 1 && backmatter_follows(lines, li - 1) {
667 self.backmatter(lines, li - 1);
668 break;
669 }
670 if let Some(m) = rx.fence.captures(&cur.text) {
671 let marker = m.get(&cur.text, 2).unwrap_or("```");
672 let info = m.get(&cur.text, 3).unwrap_or("");
673 if !(marker.starts_with('`') && info.contains('`')) {
674 literal_line(top, &cur);
675 top.code = Some(CodeFence { ch: marker.as_bytes()[0], length: marker.len() });
676 continue;
677 }
678 }
679 if let Some((h, n)) = opening_html_literal(&cur.text) {
680 literal_line(top, &cur);
681 if !rx.html_literals[h].1.is_match(&cur.text[n..]) {
682 top.html_end = Some(h);
683 }
684 continue;
685 }
686 if html_block(&cur.text) || !top.paragraph && rx.html_tag_line.is_match(&cur.text) {
687 literal_line(top, &cur);
688 top.html_blank = true;
689 continue;
690 }
691 if rx.math.is_match(&cur.text) {
692 if let Some(end) = math_end(lines, li - 1) {
693 literal_line(top, &cur);
694 top.math_end = end;
695 continue;
696 }
697 self.diag(
698 "math-unclosed",
699 Severity::Warning,
700 "a $$ display formula has no closing $$ line before the next directive; it stays as text",
701 cur.n,
702 );
703 }
704 if o.directives {
705 if let Some(m) = rx.close.captures(&cur.text)
706 && stack.len() > 1
707 {
708 let colons = m.get(&cur.text, 1).map_or(0, str::len);
709 self.close(&mut stack, colons, cur.n, false);
710 continue;
711 }
712 if let Some(m) = rx.open.captures(&cur.text) {
713 let colons = m.get(&cur.text, 1).unwrap_or("").len();
714 let kind = m.get(&cur.text, 2).unwrap_or("").to_string();
715 let rest = m.get(&cur.text, 3).unwrap_or("").to_string();
716 if self.open(&mut stack, colons, &kind, &rest, &cur) {
717 continue;
718 }
719 }
720 }
721 let top = stack.last_mut().expect("the root frame");
722 if o.keywords && self.start_unit(top, &cur) {
723 continue;
724 }
725 self.prose_line(top, &cur);
726 }
727 if comment_open {
728 self.diag("comment-unclosed", Severity::Warning, "a comment is not closed; it runs to the end of the file", comment_line);
729 }
730 while stack.len() > 1 {
731 let f = stack.last().expect("an open frame");
732 let (kind, start) = f.node.as_ref().map_or((String::new(), 0), |n| (n.kind.clone(), n.range.map_or(0, |r| r.start)));
733 let fence = f.fence;
734 self.diag(
735 "unclosed-directive",
736 Severity::Error,
737 format!(":::{kind} is not closed: end it with a line of {}", ":".repeat(fence)),
738 start,
739 );
740 let end = lines.last().map_or(start, |l| l.n);
741 self.close(&mut stack, fence, end, true);
742 }
743 let mut root = stack.pop().expect("the root frame");
744 self.end_frame(&mut root);
745 self.depth -= 1;
746 root.nodes
747 }
748
749 fn prose_line(&mut self, f: &mut Frame, ln: &Line) {
753 let rx = &*RX;
754 let t = &ln.text;
755 if !blank(t) {
756 f.last_rule = None;
757 if let Some(h) = rx.heading_attr.captures(t)
758 && let Some(list) = h.get(t, 1)
759 {
760 self.heading_identity(list, ln.n);
761 }
762 if let Some(fn_) = rx.footnote_def.captures(t)
763 && let Some(label) = fn_.get(t, 1)
764 {
765 if !registry().id_pattern().is_match(label) {
766 self.diag(
767 "invalid-attributes",
768 Severity::Error,
769 format!("the footnote label \"{label}\" is not valid: use letters, digits, \".\", \"_\" and \"-\""),
770 ln.n,
771 );
772 } else if let Some(&first) = self.r.footnotes.get(label) {
773 self.diag(
774 "footnote-duplicate",
775 Severity::Error,
776 format!("the footnote [^{label}] is defined twice (first on line {first})"),
777 ln.n,
778 );
779 } else {
780 self.r.footnotes.insert(label.to_string(), ln.n);
781 }
782 }
783 }
784 if rx.item_start.is_match(t) {
785 f.in_list = !rx.thematic.is_match(t);
786 } else {
787 f.in_list = f.in_list && (blank(t) || indent_of(t) >= 2);
788 }
789 f.prev_quote = rx.quote.is_match(t) || f.prev_quote && !blank(t) && !starts_block(t);
790 f.md.push(ln.clone());
791 f.prev_blank = blank(t);
792 f.paragraph = !blank(t) && !rx.heading.is_match(t) && !rx.thematic.is_match(t);
793 }
794
795 fn flush(&mut self, f: &mut Frame) {
796 if f.md.iter().any(|l| !blank(&l.text)) {
797 let md = std::mem::take(&mut f.md);
798 let node = self.markdown(&md);
799 f.nodes.push(node);
800 }
801 f.md.clear();
802 }
803
804 fn before_node(&mut self, f: &mut Frame) {
806 self.flush(f);
807 f.last_rule = None;
808 f.prev_blank = false;
809 f.paragraph = false;
810 f.prev_quote = false;
811 f.in_list = false;
812 }
813
814 fn push(&mut self, f: &mut Frame, node: Node) -> usize {
816 self.before_node(f);
817 let rule = is_rule(&node.kind);
818 f.nodes.push(node);
819 let at = f.nodes.len() - 1;
820 if rule {
821 f.last_rule = Some(at);
822 }
823 at
824 }
825
826 fn markdown(&mut self, lines: &[Line]) -> Node {
827 let texts: Vec<&str> = lines.iter().map(|l| l.text.as_str()).collect();
828 let mut node = Node::markdown(texts.join("\n") + "\n");
829 node.range = Some(Range::new(lines[0].n, lines[lines.len() - 1].n));
830 node.prose = true;
831 self.r.prose_order.push(ProseRef { source: node.source.clone(), range: node.range });
832 node
833 }
834
835 fn start_unit(&mut self, f: &mut Frame, ln: &Line) -> bool {
838 let rx = &*RX;
839 let t = &ln.text;
840 if let Some(alert) = rx.alert.captures(t)
841 && !f.prev_quote
842 {
843 let written = alert.get(t, 1).unwrap_or("");
844 let keyword = written.to_uppercase().split([' ', '\t']).filter(|s| !s.is_empty()).collect::<Vec<_>>().join(" ");
845 if let Some(kind) = registry().keywords.get(&keyword) {
846 let mut node = Node::directive(kind.clone(), Form::Alert, keyword_flags(&keyword));
847 node.range = Some(Range::line(ln.n));
848 node.keyword = Some(keyword);
849 let at = self.push(f, node);
850 f.unit = Some(Unit {
851 kind: UnitKind::Alert,
852 node: at,
853 rule: None,
854 lines: Vec::new(),
855 original: Vec::new(),
856 shape: Shape::Line,
857 offset: 0,
858 blanks: Vec::new(),
859 last: t.clone(),
860 });
861 return true;
862 }
863 }
864 let (shape, content, offset): (Shape, String, usize);
866 if let Some(q) = rx.quote.captures(t) {
867 shape = Shape::Quote;
868 content = q.get(t, 1).unwrap_or("").to_string();
869 offset = 0;
870 } else if let Some(item) =
871 rx.item.captures(t).filter(|item| !rx.thematic.is_match(t) && (indent_of(item.get(t, 1).unwrap_or("")) <= 3 || f.in_list))
872 {
873 shape = Shape::Item;
874 content = item.get(t, 4).unwrap_or("").to_string();
875 let mut gap = indent_of(item.get(t, 3).unwrap_or(""));
876 if gap > 4 {
877 gap = 1;
878 }
879 offset = indent_of(item.get(t, 1).unwrap_or("")) + item.get(t, 2).unwrap_or("").len() + gap;
880 } else if indent_of(t) > 3 {
881 return false;
882 } else {
883 shape = Shape::Line;
884 content = t.trim_start_matches([' ', '\t']).to_string();
885 offset = 0;
886 }
887
888 if let Some(k) = rx.keyword.captures(&content) {
889 let Some(node) = self.rule_node(&content, &k, ln) else { return false };
890 let text = k.get(&content, 6).unwrap_or("").to_string();
891 let at = self.push(f, node);
892 f.unit = Some(Unit {
893 kind: UnitKind::Rule,
894 node: at,
895 rule: None,
896 lines: vec![Line { text, n: ln.n }],
897 original: Vec::new(),
898 shape,
899 offset,
900 blanks: Vec::new(),
901 last: String::new(),
902 });
903 return true;
904 }
905 if let Some(b) = rx.because.captures(&content)
906 && b.span(1).is_none() == b.span(2).is_none()
907 {
908 let rule = f.last_rule;
909 self.flush(f);
910 f.unit = Some(Unit {
911 kind: UnitKind::Reason,
912 node: 0,
913 rule,
914 lines: vec![Line { text: b.get(&content, 3).unwrap_or("").to_string(), n: ln.n }],
915 original: vec![ln.clone()],
916 shape,
917 offset,
918 blanks: Vec::new(),
919 last: String::new(),
920 });
921 return true;
922 }
923 false
924 }
925
926 fn rule_node(&mut self, content: &str, m: &crate::pattern::Captures, ln: &Line) -> Option<Node> {
928 let open = m.get(content, 1).unwrap_or("");
929 let keyword = m.get(content, 2).unwrap_or("").to_string();
930 let id = m.get(content, 3);
931 let cond = m.get(content, 4);
932 let closing = m.get(content, 5).unwrap_or("");
933 if open.is_empty() != closing.is_empty() {
934 return None;
935 }
936 let kind = registry().keywords.get(&keyword).cloned().unwrap_or_default();
937 let mut attrs = Attrs::new();
938 if let Some(id) = id {
939 if registry().id_pattern().is_match(id) {
940 attrs.insert("id".into(), Value::String(id.to_string()));
941 } else {
942 self.diag(
943 "invalid-attributes",
944 Severity::Error,
945 format!("\"{id}\" is not a valid rule name: use letters, digits, \".\", \"_\" and \"-\""),
946 ln.n,
947 );
948 }
949 }
950 if let Some(cond) = cond {
951 if !is_rule(&kind) {
952 self.diag(
953 "invalid-attributes",
954 Severity::Error,
955 format!("{keyword} is advice, not a rule: it takes no (if …) condition"),
956 ln.n,
957 );
958 } else if js_trim(cond).is_empty() {
959 self.diag("invalid-attributes", Severity::Error, "a rule's (if …) condition is not empty", ln.n);
960 } else {
961 attrs.insert("if".into(), Value::String(cond.to_string()));
962 }
963 }
964 for (k, v) in keyword_flags(&keyword) {
965 attrs.insert(k, v);
966 }
967 let mut node = Node::directive(kind.clone(), Form::Keyword, attrs);
968 node.range = Some(Range::line(ln.n));
969 node.keyword = Some(keyword);
970 if let Some(Value::String(id)) = node.attrs.get("id").cloned() {
971 self.identity(&id, &kind, ln.n);
972 }
973 Some(node)
974 }
975
976 fn continue_unit(&mut self, f: &mut Frame, ln: &Line) -> bool {
978 let rx = &*RX;
979 let t = &ln.text;
980 let Some(u) = f.unit.as_mut() else { return false };
981 if u.kind == UnitKind::Alert {
982 if let Some(q) = rx.quote.captures(t) {
983 let text = q.get(t, 1).unwrap_or("").to_string();
984 u.last = text.clone();
985 u.lines.push(Line { text, n: ln.n });
986 return true;
987 }
988 if !blank(t) && !blank(&u.last) && !starts_block(t) {
989 u.lines.push(Line { text: js_trim(t).to_string(), n: ln.n });
990 u.last = t.clone();
991 return true;
992 }
993 return false;
994 }
995 let keep = |u: &mut Unit, text: String| {
996 if u.kind == UnitKind::Reason {
997 u.original.push(ln.clone());
998 }
999 u.lines.push(Line { text, n: ln.n });
1000 true
1001 };
1002 match u.shape {
1003 Shape::Quote => {
1004 if let Some(q) = rx.quote.captures(t) {
1005 let inner = q.get(t, 1).unwrap_or("");
1006 if blank(inner) || rx.keyword.is_match(inner) || rx.because.is_match(inner) {
1007 return false;
1008 }
1009 return keep(u, inner.to_string());
1010 }
1011 if blank(t) || starts_block(t) {
1012 return false;
1013 }
1014 keep(u, js_trim(t).to_string())
1015 }
1016 Shape::Item => {
1017 if blank(t) {
1018 u.blanks.push(ln.clone());
1019 return true;
1020 }
1021 if indent_of(t) >= u.offset {
1022 let inner = dedent(t, u.offset);
1023 if u.kind == UnitKind::Rule
1024 && u.blanks.is_empty()
1025 && let Some(b) = rx.because.captures(inner)
1026 {
1027 let rule = u.node;
1029 let offset = u.offset;
1030 let reason = b.get(inner, 3).unwrap_or("").to_string();
1031 self.end_unit(f);
1032 f.unit = Some(Unit {
1033 kind: UnitKind::Reason,
1034 node: 0,
1035 rule: Some(rule),
1036 lines: vec![Line { text: reason, n: ln.n }],
1037 original: vec![ln.clone()],
1038 shape: Shape::Item,
1039 offset,
1040 blanks: Vec::new(),
1041 last: String::new(),
1042 });
1043 return true;
1044 }
1045 let inner = inner.to_string();
1046 let blanks = std::mem::take(&mut u.blanks);
1047 if u.kind == UnitKind::Reason {
1048 u.original.extend(blanks.iter().cloned());
1049 u.original.push(ln.clone());
1050 }
1051 u.lines.extend(blanks);
1052 u.lines.push(Line { text: inner, n: ln.n });
1053 return true;
1054 }
1055 if !u.blanks.is_empty() || starts_block(t) || interrupts(t) {
1056 return false;
1057 }
1058 keep(u, js_trim(t).to_string())
1059 }
1060 Shape::Line => {
1061 if blank(t) || starts_block(t) || interrupts(t) {
1063 return false;
1064 }
1065 keep(u, t.clone())
1066 }
1067 }
1068 }
1069
1070 fn end_unit(&mut self, f: &mut Frame) {
1071 let Some(u) = f.unit.take() else { return };
1072 if u.kind == UnitKind::Alert {
1073 let children = self.scope(&u.lines, ScopeOptions::default());
1074 if let Some(node) = f.nodes.get_mut(u.node) {
1075 node.children = Some(children);
1076 let start = node.range.map_or(0, |r| r.start);
1077 let end = u.lines.last().map_or(start, |l| l.n);
1078 node.range = Some(Range::new(start, end));
1079 f.last_rule = is_rule(&node.kind).then_some(u.node);
1080 }
1081 return;
1082 }
1083 let pending = u.blanks;
1084 if u.kind == UnitKind::Rule {
1085 let children = if u.shape == Shape::Item {
1086 self.scope(&u.lines, ScopeOptions { keywords: true, ..ScopeOptions::default() })
1087 } else {
1088 vec![self.markdown(&u.lines)]
1089 };
1090 if let Some(node) = f.nodes.get_mut(u.node) {
1091 node.children = Some(children);
1092 let start = node.range.map_or(0, |r| r.start);
1093 node.range = Some(Range::new(start, u.lines.last().map_or(start, |l| l.n)));
1094 }
1095 f.last_rule = Some(u.node);
1096 } else {
1097 let texts: Vec<&str> = u.lines.iter().map(|l| l.text.as_str()).collect();
1098 let first = u.lines.first().map_or(0, |l| l.n);
1099 match u.rule {
1100 None => {
1101 self.diag(
1102 "orphan-reason",
1103 Severity::Warning,
1104 "BECAUSE: follows no rule here, so it stays prose: put it right after the rule it explains",
1105 first,
1106 );
1107 for l in &u.original {
1108 self.prose_line(f, l);
1109 }
1110 }
1111 Some(rule) if f.nodes.get(rule).is_some_and(|n| n.attrs.contains_key("because")) => {
1112 self.diag("reason-repeated", Severity::Error, "this rule already has a reason: give it one BECAUSE", first);
1113 for l in &u.original {
1114 self.prose_line(f, l);
1115 }
1116 }
1117 Some(rule) => {
1118 if let Some(node) = f.nodes.get_mut(rule) {
1119 node.attrs.insert("because".into(), Value::String(texts.join("\n")));
1120 node.reason = Some(Range::new(first, u.lines.last().map_or(first, |l| l.n)));
1121 }
1122 f.last_rule = Some(rule);
1123 }
1124 }
1125 }
1126 for l in &pending {
1127 self.prose_line(f, l);
1128 }
1129 }
1130
1131 fn open(&mut self, stack: &mut Vec<Frame>, colons: usize, kind: &str, rest: &str, ln: &Line) -> bool {
1134 let rest = rest.trim_end_matches([' ', '\t']);
1135 let mut attr_text = "";
1136 let mut has_attrs = false;
1137 let mut attr_broken = false;
1138 if !rest.is_empty() {
1139 if !rest.starts_with('{') {
1140 return false; }
1142 if attributes_end(rest, 0) == Some(rest.len()) {
1143 attr_text = &rest[1..rest.len() - 1];
1144 has_attrs = true;
1145 } else {
1146 attr_broken = true;
1147 }
1148 }
1149 let leaf = colons == 2;
1150 let spec = registry::kind(kind);
1151 let extension = kind.contains(':');
1152 let (form, where_) = if leaf { (Form::Leaf, format!("::{kind}")) } else { (Form::Container, format!(":::{kind}")) };
1153 if !leaf && stack.len() > MAX_NESTING {
1154 self.diag(
1155 "invalid-nesting",
1156 Severity::Error,
1157 format!("{where_} opens deeper than {MAX_NESTING} directives; it stays prose"),
1158 ln.n,
1159 );
1160 return false;
1161 }
1162 let mut node = Node::directive(kind, form, Attrs::new());
1163 node.range = Some(Range::line(ln.n));
1164 if attr_broken {
1165 self.diag(
1166 "invalid-attributes",
1167 Severity::Error,
1168 format!("{where_}: its attribute list must close with }} at the end of the line"),
1169 ln.n,
1170 );
1171 }
1172 if has_attrs {
1173 let owned_kind = kind.to_string();
1174 let spec_of = move |key: &str| -> Option<&'static AttrSpec> {
1175 spec?;
1176 attr_spec(&owned_kind, key)
1177 };
1178 let (attrs, problems) = parse_attributes(attr_text, &spec_of, spec.is_some());
1179 node.attrs = attrs;
1180 for p in problems {
1181 self.diag("invalid-attributes", Severity::Error, format!("{where_}: {p}"), ln.n);
1182 }
1183 }
1184 if spec.is_none() && !extension {
1185 self.diag(
1186 "unknown-kind",
1187 Severity::Error,
1188 format!("{where_} is not a kind of this specification; it is kept as written, uninterpreted"),
1189 ln.n,
1190 );
1191 }
1192 if extension {
1193 let alias = kind.split(':').next().unwrap_or("");
1194 let declared = self.front.get("extensions").and_then(Value::as_object).and_then(|e| e.get(alias));
1195 if !truthy(declared) {
1196 self.diag(
1197 "extension-unavailable",
1198 Severity::Error,
1199 format!("{where_}: the extension alias \"{alias}\" is not declared in the front matter's extensions"),
1200 ln.n,
1201 );
1202 }
1203 }
1204 if let Some(spec) = spec {
1205 self.check_directive(&node, spec, stack, ln.n, &where_);
1206 }
1207 if let Some(id) = node.attrs.get("id") {
1208 let id = js_value(Some(id));
1209 self.identity(&id, kind, ln.n);
1210 }
1211 if kind == "include"
1212 && let Some(Value::String(alias)) = node.attrs.get("as")
1213 {
1214 if self.aliases.contains(alias) {
1215 self.diag("duplicate-id", Severity::Error, format!("the include alias \"{alias}\" is used twice"), ln.n);
1216 }
1217 self.aliases.insert(alias.clone());
1218 }
1219 let depth = stack.len();
1220 let top = stack.last_mut().expect("the root frame");
1221 if top.unit.is_some() {
1222 self.end_unit(top);
1223 }
1224 if leaf {
1225 if kind == "param" {
1226 self.param_leaf(&node, ln.n);
1227 }
1228 self.push(top, node);
1229 return true;
1230 }
1231 if depth > 1 && colons >= top.fence {
1232 self.diag(
1233 "invalid-nesting",
1234 Severity::Error,
1235 format!(
1236 "{where_} opens inside a {} container with as many colons or more: an inner fence is shorter than its outer one",
1237 ":".repeat(top.fence)
1238 ),
1239 ln.n,
1240 );
1241 }
1242 let mut body = BodyKind::Parsed;
1243 let mut format = "markdown".to_string();
1244 match spec {
1245 None => body = BodyKind::Opaque,
1246 Some(spec) => {
1247 format = if spec.body == "yaml" { "yaml".into() } else { "markdown".into() };
1249 if let Some(Value::String(chosen)) = node.attrs.get("format")
1250 && spec.formats().contains(chosen)
1251 {
1252 format = chosen.clone();
1253 }
1254 if format != "markdown" {
1255 body = BodyKind::Structured;
1256 } else if spec.opaque || node.attrs.get("verbatim") == Some(&Value::Bool(true)) {
1257 body = BodyKind::Literal;
1258 }
1259 }
1260 }
1261 let top = stack.last_mut().expect("the root frame");
1262 self.before_node(top);
1263 stack.push(Frame::new(Some(node), colons, body, &format));
1264 true
1265 }
1266
1267 fn check_directive(&mut self, node: &Node, spec: &KindSpec, stack: &[Frame], at: u32, where_: &str) {
1268 let form = node.form.map_or("container", Form::as_str);
1269 if !spec.takes(form) {
1270 let forms: Vec<String> = spec
1271 .forms
1272 .iter()
1273 .filter_map(|f| match f.as_str() {
1274 "leaf" => Some(format!("::{}{{…}}", node.kind)),
1275 "container" => Some(format!(":::{} … :::", node.kind)),
1276 _ => None,
1277 })
1278 .collect();
1279 self.diag("invalid-nesting", Severity::Error, format!("{where_}: {} is written {}", node.kind, forms.join(" or ")), at);
1280 }
1281 for key in &spec.required {
1282 match node.attrs.get(key) {
1283 None => self.diag("invalid-attributes", Severity::Error, format!("{where_} needs {key}=…"), at),
1284 Some(Value::String(s)) if s.is_empty() => {
1285 self.diag("invalid-attributes", Severity::Error, format!("{where_} needs {key}=…"), at)
1286 }
1287 _ => {}
1288 }
1289 }
1290 if let Some(parent) = &spec.parent {
1291 let actual = stack.iter().rev().find_map(|f| f.node.as_ref().map(|n| n.kind.as_str())).unwrap_or("");
1292 if actual != parent {
1293 self.diag("invalid-nesting", Severity::Error, format!("{where_} belongs inside :::{parent}"), at);
1294 }
1295 }
1296 let a = &node.attrs;
1297 if let Some(Value::String(format)) = a.get("format")
1298 && !spec.formats().contains(format)
1299 {
1300 self.diag("invalid-attributes", Severity::Error, format!("{where_}: format is {}", spec.formats().join(" or ")), at);
1301 }
1302 if is_str(a.get("mode"), "pinned") && !a.contains_key("sha256") {
1303 self.diag("pin-mismatch", Severity::Error, format!("{where_}: a pinned reference needs sha256=sha256:<64 hex>"), at);
1304 }
1305 if spec.family == "connected"
1307 && let Some(Value::String(p)) = a.get("protocol")
1308 && !crate::allowance::protocol_ok(p)
1309 {
1310 self.diag(
1311 "protocol-syntax",
1312 Severity::Error,
1313 format!("{where_}: protocol is a name, optionally with versions: a2a, x402/2, mcp/2026-07-28 or com.example/rail/1 (it is \"{p}\")"),
1314 at,
1315 );
1316 }
1317 if node.kind == "allowance" {
1319 for p in crate::allowance::problems(a) {
1320 self.diag(p.code, Severity::Error, format!("{where_}: {}", p.message), at);
1321 if let (Some(Value::String(id)), Some(d)) = (a.get("id"), self.r.diagnostics.last_mut()) {
1323 d.target = format!("#{id}");
1324 }
1325 }
1326 }
1327 if let (Some(start), Some(end)) = (a.get("start").and_then(Value::as_f64), a.get("end").and_then(Value::as_f64))
1328 && end <= start
1329 {
1330 self.diag("invalid-attributes", Severity::Error, format!("{where_}: end is after start"), at);
1331 }
1332 if let Some(Value::String(region)) = a.get("region")
1333 && !valid_region(region)
1334 {
1335 self.diag(
1336 "invalid-attributes",
1337 Severity::Error,
1338 format!("{where_}: region is x,y,width,height, fractions in [0,1] inside the unit square"),
1339 at,
1340 );
1341 }
1342 }
1343
1344 fn close(&mut self, stack: &mut Vec<Frame>, colons: usize, n: u32, at_eof: bool) {
1345 let Some(mut f) = stack.pop() else { return };
1346 let kind = f.node.as_ref().map_or(String::new(), |node| node.kind.clone());
1347 if !at_eof && colons < f.fence {
1348 self.diag(
1349 "invalid-nesting",
1350 Severity::Error,
1351 format!("the closing fence on line {n} is shorter than the :::{kind} it closes ({} colons)", f.fence),
1352 n,
1353 );
1354 }
1355 if let Some(node) = f.node.as_mut() {
1356 let start = node.range.map_or(n, |r| r.start);
1357 node.range = Some(Range::new(start, n));
1358 let from = self.r.line_offset(start + 1);
1360 let to = if at_eof { self.r.source.len() } else { self.r.line_offset(n) };
1361 node.body = Some(Span { text: self.r.source.clone(), start: from, end: to.max(from) });
1362 }
1363 self.end_frame(&mut f);
1364 let Some(node) = f.node.take() else { return };
1365 let Some(parent) = stack.last_mut() else { return };
1366 let rule = is_rule(&node.kind);
1367 parent.nodes.push(node);
1368 parent.last_rule = rule.then_some(parent.nodes.len() - 1);
1369 parent.prev_blank = false;
1370 parent.paragraph = false;
1371 parent.prev_quote = false;
1372 parent.in_list = false;
1373 }
1374
1375 fn end_frame(&mut self, f: &mut Frame) {
1376 if f.body == BodyKind::Parsed {
1377 if f.unit.is_some() {
1378 self.end_unit(f);
1379 }
1380 self.flush(f);
1381 if let Some(node) = f.node.as_mut() {
1382 node.children = Some(std::mem::take(&mut f.nodes));
1383 }
1384 return;
1385 }
1386 let Some(node) = f.node.as_mut() else { return };
1387 let text =
1388 if f.raw.is_empty() { String::new() } else { f.raw.iter().map(|l| l.text.as_str()).collect::<Vec<_>>().join("\n") + "\n" };
1389 let start = node.range.map_or(0, |r| r.start);
1390 let at = f.raw.first().map_or(start, |l| l.n);
1391 if f.body == BodyKind::Literal || f.body == BodyKind::Opaque {
1392 let mut children = Vec::new();
1393 if !text.is_empty() {
1394 let mut md = Node::markdown(text.clone());
1395 md.range = Some(Range::new(at, f.raw.last().map_or(at, |l| l.n)));
1396 children.push(md);
1397 }
1398 node.children = Some(children);
1399 if f.body == BodyKind::Opaque {
1400 let end = node.range.map_or(start, |r| r.end) as usize;
1401 let from = (start as usize).saturating_sub(1).min(self.r.lines.len());
1402 let to = end.min(self.r.lines.len()).max(from);
1403 node.source = self.r.lines[from..to].join("\n") + "\n";
1404 }
1405 return;
1406 }
1407 let kind = node.kind.clone();
1408 let mut value =
1409 crate::types::StructuredValue { format: f.format.clone(), source: text.clone(), data: None, order: KeyOrder::default() };
1410 let upper = f.format.to_uppercase();
1411 let mut problems: Vec<String> = Vec::new();
1412 match f.format.as_str() {
1413 "yaml" | "json" => {
1414 let loaded = if f.format == "yaml" { load_yaml(&text) } else { load_json(&text) };
1415 match loaded {
1416 Err(e) => problems.push(format!(":::{kind}: its {upper} body is invalid: {e}")),
1417 Ok((data, order)) => {
1418 if kind != "data" && !data.is_object() {
1420 problems.push(format!(":::{kind}: its body is a {upper} mapping"));
1421 }
1422 value.data = Some(data);
1423 value.order = order;
1424 }
1425 }
1426 }
1427 "csv" => match load_csv(&text) {
1428 Err(e) => problems.push(format!(":::{kind}: {e}")),
1429 Ok((header, rows)) => {
1430 let records = rows
1431 .into_iter()
1432 .map(|row| {
1433 let mut record = Map::new();
1434 for (h, cell) in header.iter().zip(row) {
1435 record.insert(h.clone(), Value::String(cell));
1436 }
1437 Value::Object(record)
1438 })
1439 .collect();
1440 value.data = Some(Value::Array(records));
1441 }
1442 },
1443 _ => {}
1444 }
1445 node.value = Some(value);
1446 for p in problems {
1447 self.diag("invalid-structured-body", Severity::Error, p, at);
1448 }
1449 }
1450
1451 fn raw_line(&mut self, stack: &mut Vec<Frame>, ln: &Line) {
1453 let rx = &*RX;
1454 let Some(f) = stack.last_mut() else { return };
1455 if let Some(code) = f.raw_code {
1456 f.raw.push(ln.clone());
1457 if closes_fence(&ln.text, code) {
1458 f.raw_code = None;
1459 }
1460 return;
1461 }
1462 if let Some(m) = rx.close.captures(&ln.text) {
1463 let colons = m.get(&ln.text, 1).map_or(0, str::len);
1464 if colons >= f.fence {
1465 self.close(stack, colons, ln.n, false);
1466 return;
1467 }
1468 }
1469 if f.body == BodyKind::Literal
1470 && let Some(m) = rx.fence.captures(&ln.text)
1471 {
1472 let marker = m.get(&ln.text, 2).unwrap_or("```");
1473 let info = m.get(&ln.text, 3).unwrap_or("");
1474 if !(marker.starts_with('`') && info.contains('`')) {
1475 f.raw_code = Some(CodeFence { ch: marker.as_bytes()[0], length: marker.len() });
1476 }
1477 }
1478 f.raw.push(ln.clone());
1479 }
1480
1481 fn backmatter(&mut self, lines: &[Line], li: usize) {
1484 let rest = &lines[li + 1..];
1485 let end = rest.last().map_or(lines[li].n, |l| l.n);
1486 self.r.back_range = Some(Range::new(lines[li].n, end));
1487 let text = rest.iter().map(|l| l.text.as_str()).collect::<Vec<_>>().join("\n");
1488 let (back, _) = self.metadata(&text, lines[li].n + 1, "backmatter");
1489 self.back = back;
1490 if let Some(sources) = self.back.get("sources")
1491 && !sources.is_array()
1492 {
1493 self.diag("invalid-metadata", Severity::Error, "the backmatter's sources are a list of {id, title, uri} records", lines[li].n);
1494 }
1495 }
1496
1497 fn check_front(&mut self) {
1498 let at = self.r.front_range.map_or(1, |r| r.start);
1499 if let Some(spec) = self.front.get("spec").cloned() {
1500 let spec = if spec.as_f64() == Some(1.0) {
1501 self.front.insert("spec".into(), Value::String("1".into()));
1502 Value::String("1".into())
1503 } else {
1504 spec
1505 };
1506 if !is_str(Some(&spec), "1") {
1507 self.diag(
1508 "unsupported-format",
1509 Severity::Error,
1510 format!("spec: \"{}\" is not a format this reader knows; it reads spec: \"1\"", js_value(Some(&spec))),
1511 at,
1512 );
1513 }
1514 }
1515 for key in ["id", "version", "title", "description", "language", "license"] {
1516 if let Some(v) = self.front.get(key)
1517 && !v.is_string()
1518 {
1519 self.diag("invalid-metadata", Severity::Error, format!("the front matter's {key} is a string"), at);
1520 }
1521 }
1522 if let Some(tags) = self.front.get("tags")
1523 && !string_list(tags)
1524 {
1525 self.diag("invalid-metadata", Severity::Error, "the front matter's tags are a list of strings", at);
1526 }
1527 for key in ["parameters", "extensions", "references", "resolvers", "exports", "presentation"] {
1528 if let Some(v) = self.front.get(key)
1529 && !v.is_object()
1530 {
1531 self.diag("invalid-metadata", Severity::Error, format!("the front matter's {key} is a mapping"), at);
1532 }
1533 }
1534 if let Some(ext) = self.front.get("extends").cloned() {
1535 match ext {
1536 Value::Array(list) => {
1537 for base in list {
1538 let uri = base.get("uri").and_then(Value::as_str);
1539 let alias = base.get("as").and_then(Value::as_str);
1540 match (uri, alias) {
1541 (Some(_), Some(alias)) => {
1542 if self.aliases.contains(alias) {
1543 self.diag("duplicate-id", Severity::Error, format!("the base alias \"{alias}\" is used twice"), at);
1544 } else {
1545 self.aliases.insert(alias.to_string());
1546 }
1547 }
1548 _ => self.diag("invalid-metadata", Severity::Error, "each extends record has a uri and an as alias", at),
1549 }
1550 }
1551 }
1552 _ => self.diag("invalid-metadata", Severity::Error, "extends is a list of {uri, as} records", at),
1553 }
1554 }
1555 let extensions = self.front.get("extensions").and_then(Value::as_object).cloned().unwrap_or_default();
1557 for alias in self.front_order.keys("extensions", &extensions) {
1558 let b = extensions.get(&alias);
1559 let has_id = b.and_then(|b| b.get("id")).is_some_and(Value::is_string);
1560 let has_version = b.and_then(|b| b.get("version")).is_some_and(Value::is_string);
1561 if !has_id || !has_version {
1562 self.diag("invalid-metadata", Severity::Error, format!("the extension \"{alias}\" binds an exact id and version"), at);
1563 }
1564 }
1565 if let Some(req) = self.front.get("requires").cloned() {
1566 match req {
1567 Value::Array(list) => {
1568 for alias in list {
1569 let declared = alias.as_str().is_some_and(|name| extensions.contains_key(name));
1570 if !declared {
1571 self.diag(
1572 "extension-unavailable",
1573 Severity::Error,
1574 format!("requires names \"{}\", which the extensions do not declare", js_value(Some(&alias))),
1575 at,
1576 );
1577 }
1578 }
1579 }
1580 _ => self.diag("invalid-metadata", Severity::Error, "requires is a list of extension aliases", at),
1581 }
1582 }
1583 if let Some(Value::Object(params)) = self.front.get("parameters").cloned() {
1584 for name in self.front_order.keys("parameters", ¶ms) {
1585 match params.get(&name) {
1586 Some(Value::Object(decl)) => self.declare(&name, decl, 0, at),
1587 _ => {
1588 self.diag("parameter-invalid", Severity::Error, format!("the parameter \"{name}\" is declared with a mapping"), at)
1589 }
1590 }
1591 }
1592 }
1593 }
1594
1595 fn param_leaf(&mut self, node: &Node, at: u32) {
1596 if let Some(Value::String(name)) = node.attrs.get("name") {
1597 self.declare(&name.clone(), &node.attrs, at, at);
1598 }
1599 }
1600
1601 fn declare(&mut self, name: &str, d: &Object, declared_at: u32, at: u32) {
1602 if !registry().parameter_pattern().is_match(name) {
1603 self.diag("parameter-invalid", Severity::Error, format!("\"{name}\" is not a valid parameter name"), at);
1604 return;
1605 }
1606 if self.r.parameter_index.contains_key(name) {
1607 self.diag("parameter-invalid", Severity::Error, format!("the parameter \"{name}\" is declared twice"), at);
1608 return;
1609 }
1610 let mut p = Parameter {
1611 name: name.to_string(),
1612 param_type: "string".into(),
1613 required: d.get("required") == Some(&Value::Bool(true)),
1614 line: declared_at,
1615 ..Parameter::default()
1616 };
1617 if let Some(Value::String(t)) = d.get("type") {
1618 p.param_type = t.clone();
1619 }
1620 match d.get("values") {
1621 Some(Value::Array(list)) => p.values = Some(list.iter().map(|x| js_value(Some(x))).collect()),
1622 Some(Value::String(s)) => p.values = Some(s.split(',').map(|x| js_trim(x).to_string()).collect()),
1623 _ => {}
1624 }
1625 p.default = d.get("default").cloned();
1626 p.example = d.get("example").cloned();
1627 if let Some(Value::String(s)) = d.get("description") {
1628 p.description = Some(s.clone());
1629 }
1630 if let Some(Value::String(s)) = d.get("source") {
1631 p.source = Some(s.clone());
1632 }
1633 self.r.parameter_index.insert(name.to_string(), self.r.parameters.len());
1634 self.r.parameters.push(p);
1635 }
1636
1637 fn check_parameters(&mut self) {
1638 let front_at = self.r.front_range.map_or(1, |r| r.start);
1639 let params = self.r.parameters.clone();
1640 for p in ¶ms {
1641 let at = if p.line == 0 { front_at } else { p.line };
1642 if !PARAMETER_TYPES.contains(&p.param_type.as_str()) {
1643 self.diag(
1644 "parameter-invalid",
1645 Severity::Error,
1646 format!("the parameter \"{}\" has an unknown type \"{}\"", p.name, p.param_type),
1647 at,
1648 );
1649 continue;
1650 }
1651 if p.param_type == "enum" && !p.values.as_ref().is_some_and(|v| !v.is_empty() && !v.iter().any(String::is_empty)) {
1652 self.diag("parameter-invalid", Severity::Error, format!("the enum parameter \"{}\" lists its values", p.name), at);
1653 }
1654 if let Some(d) = &p.default
1655 && !value_fits(p, d)
1656 {
1657 self.diag(
1658 "parameter-invalid",
1659 Severity::Error,
1660 format!("the default of \"{}\" is not a valid {}", p.name, p.param_type),
1661 at,
1662 );
1663 }
1664 }
1665 }
1666
1667 fn identity(&mut self, id: &str, kind: &str, at: u32) {
1670 if let Some(first) = self.r.identity(id).map(|i| i.line) {
1671 self.diag(
1672 "duplicate-id",
1673 Severity::Error,
1674 format!("the id \"{id}\" is used twice (first on line {first}); ids are unique in a document"),
1675 at,
1676 );
1677 return;
1678 }
1679 self.r.add_identity(Identity { id: id.to_string(), kind: kind.to_string(), line: at }, false);
1680 }
1681
1682 fn heading_identity(&mut self, list: &str, at: u32) {
1683 let spec_of = |key: &str| -> Option<&'static AttrSpec> {
1684 if matches!(key, "id" | "class" | "style") { attr_spec("section", key) } else { None }
1685 };
1686 let inner = list.get(1..list.len().saturating_sub(1)).unwrap_or("");
1687 let (attrs, problems) = parse_attributes(inner, &spec_of, true);
1688 for p in problems {
1689 self.diag(
1690 "invalid-attributes",
1691 Severity::Error,
1692 format!("heading attributes: {p}; a heading takes only id, class and style"),
1693 at,
1694 );
1695 }
1696 if let Some(Value::String(id)) = attrs.get("id") {
1697 self.identity(id, "heading", at);
1698 }
1699 }
1700}
1701
1702const PARAMETER_TYPES: &[&str] = &["string", "number", "integer", "boolean", "enum", "list", "url", "duration"];
1703
1704fn keyword_flags(keyword: &str) -> Attrs {
1705 let mut attrs = Attrs::new();
1706 if let Some(flags) = registry().keyword_flags.get(keyword) {
1707 for (k, v) in flags {
1708 attrs.insert(k.clone(), v.clone());
1709 }
1710 }
1711 attrs
1712}
1713
1714fn literal_line(f: &mut Frame, ln: &Line) {
1716 f.md.push(ln.clone());
1717 f.last_rule = None;
1718 f.prev_blank = false;
1719 f.paragraph = false;
1720 f.prev_quote = false;
1721}
1722
1723fn opening_html_literal(t: &str) -> Option<(usize, usize)> {
1725 for (i, (open, _)) in RX.html_literals.iter().enumerate() {
1726 if let Some(c) = open.captures(t)
1727 && let Some((_, end)) = c.span(1)
1728 {
1729 return Some((i, end));
1730 }
1731 }
1732 None
1733}
1734
1735fn html_block(t: &str) -> bool {
1736 RX.html_block.is_match(t)
1737}
1738
1739fn closes_fence(text: &str, f: CodeFence) -> bool {
1742 match RX.closer.captures(text).and_then(|m| m.get(text, 1).map(str::to_string)) {
1743 Some(run) => run.as_bytes()[0] == f.ch && run.len() >= f.length,
1744 None => false,
1745 }
1746}
1747
1748pub(crate) fn starts_block(t: &str) -> bool {
1750 let rx = &*RX;
1751 rx.heading.is_match(t)
1752 || rx.thematic.is_match(t)
1753 || rx.quote_start.is_match(t)
1754 || rx.item_start.is_match(t)
1755 || rx.fence.is_match(t)
1756 || rx.math.is_match(t)
1757 || rx.directive.is_match(t)
1758 || rx.close.is_match(t)
1759 || html_block(t)
1760 || opening_html_literal(t).is_some()
1761}
1762
1763fn interrupts(t: &str) -> bool {
1765 let mut s = t;
1766 for _ in 0..3 {
1767 match s.strip_prefix(' ') {
1768 Some(rest) => s = rest,
1769 None => break,
1770 }
1771 }
1772 RX.keyword.is_match(s) || RX.because.is_match(s)
1773}
1774
1775fn dedent(t: &str, n: usize) -> &str {
1777 let b = t.as_bytes();
1778 let (mut col, mut i) = (0, 0);
1779 while i < b.len() && col < n && (b[i] == b' ' || b[i] == b'\t') {
1780 if b[i] == b'\t' {
1781 col += 4 - col % 4;
1782 } else {
1783 col += 1;
1784 }
1785 i += 1;
1786 }
1787 &t[i..]
1788}
1789
1790fn backmatter_follows(lines: &[Line], li: usize) -> bool {
1792 for l in &lines[li + 1..] {
1793 if blank(&l.text) || RX.yaml_comment.is_match(&l.text) {
1794 continue;
1795 }
1796 return RX.backmatter.is_match(&l.text);
1797 }
1798 false
1799}
1800
1801fn math_end(lines: &[Line], li: usize) -> Option<u32> {
1804 for l in &lines[li + 1..] {
1805 if RX.math.is_match(&l.text) {
1806 return Some(l.n);
1807 }
1808 if RX.close.is_match(&l.text) {
1809 return None;
1810 }
1811 }
1812 None
1813}
1814
1815#[derive(Clone, Debug, PartialEq, Eq)]
1817pub struct Stripped {
1818 pub text: String,
1820 pub still_open: bool,
1822 pub opened: bool,
1824 pub only: bool,
1826}
1827
1828pub fn strip_comments(ln: &str, open: bool) -> Stripped {
1831 let mut open = open;
1832 let mut out = String::new();
1833 let mut removed = false;
1834 let mut opened = false;
1835 let b = ln.as_bytes();
1836 let mut i = 0;
1837 while i < b.len() {
1838 if open {
1839 removed = true;
1840 match ln[i..].find("-->") {
1841 None => break,
1842 Some(end) => {
1843 open = false;
1844 i += end + 3;
1845 continue;
1846 }
1847 }
1848 }
1849 let c = b[i];
1850 if c == b'\\' {
1851 let end = (i + 2).min(b.len());
1852 let end = if ln.is_char_boundary(end) { end } else { next_boundary(ln, end) };
1853 out.push_str(&ln[i..end]);
1854 i = end;
1855 continue;
1856 }
1857 if c == b'`' {
1858 let mut run = 0;
1859 while i + run < b.len() && b[i + run] == b'`' {
1860 run += 1;
1861 }
1862 let ticks = &ln[i..i + run];
1864 if let Some(close) = ln[i + run..].find(ticks) {
1865 let close = close + i + run;
1866 if close + run >= b.len() || b[close + run] != b'`' {
1867 out.push_str(&ln[i..close + run]);
1868 i = close + run;
1869 continue;
1870 }
1871 }
1872 out.push_str(ticks);
1873 i += run;
1874 continue;
1875 }
1876 if ln[i..].starts_with("<!--") {
1877 open = true;
1878 opened = true;
1879 removed = true;
1880 i += 4;
1881 continue;
1882 }
1883 let end = next_boundary(ln, i + 1);
1884 out.push_str(&ln[i..end]);
1885 i = end;
1886 }
1887 if removed && blank(&out) {
1888 return Stripped { text: String::new(), still_open: open, opened, only: true };
1889 }
1890 Stripped { text: out, still_open: open, opened, only: false }
1891}
1892
1893fn next_boundary(s: &str, mut i: usize) -> usize {
1894 while i < s.len() && !s.is_char_boundary(i) {
1895 i += 1;
1896 }
1897 i.min(s.len())
1898}
1899
1900fn valid_region(s: &str) -> bool {
1901 let parts: Vec<&str> = s.split(',').collect();
1902 if parts.len() != 4 {
1903 return false;
1904 }
1905 let mut v = [0.0f64; 4];
1906 for (i, p) in parts.iter().enumerate() {
1907 let p = js_trim(p);
1908 if !RX.region_part.is_match(p) {
1909 return false;
1910 }
1911 v[i] = p.parse().unwrap_or(0.0);
1912 }
1913 let [x, y, w, h] = v;
1914 w > 0.0 && h > 0.0 && x + w <= 1.0 && y + h <= 1.0
1915}
1916
1917pub fn value_from(p: &Parameter, text: &str) -> Value {
1921 match p.param_type.as_str() {
1922 "number" | "integer" => {
1923 if let Some(n) = js_to_number(text)
1924 && !js_trim(text).is_empty()
1925 && !n.is_infinite()
1926 {
1927 return num(n);
1928 }
1929 }
1930 "boolean" => match text {
1931 "true" => return Value::Bool(true),
1932 "false" => return Value::Bool(false),
1933 _ => {}
1934 },
1935 "list" => {
1936 if js_trim(text).is_empty() {
1937 return Value::Array(Vec::new());
1938 }
1939 return Value::Array(text.split(',').map(|x| Value::String(js_trim(x).to_string())).collect());
1940 }
1941 _ => {}
1942 }
1943 Value::String(text.to_string())
1944}
1945
1946fn js_to_number(text: &str) -> Option<f64> {
1948 let s = js_trim(text);
1949 if s.is_empty() {
1950 return Some(0.0);
1951 }
1952 if s == "Infinity" || s == "+Infinity" {
1953 return Some(f64::INFINITY);
1954 }
1955 if s == "-Infinity" {
1956 return Some(f64::NEG_INFINITY);
1957 }
1958 if RX.decimal.is_match(s) {
1959 return s.parse().ok();
1960 }
1961 let b = s.as_bytes();
1962 if b.len() > 2 && b[0] == b'0' && b[2] != b'+' && b[2] != b'-' {
1963 let base = match b[1] {
1964 b'x' | b'X' => 16,
1965 b'o' | b'O' => 8,
1966 b'b' | b'B' => 2,
1967 _ => return None,
1968 };
1969 let mut v = 0.0f64;
1970 let mut exact: Option<u128> = Some(0);
1971 for c in s[2..].chars() {
1972 let d = c.to_digit(base)?;
1973 exact = exact.and_then(|e| e.checked_mul(base as u128)).and_then(|e| e.checked_add(d as u128));
1974 v = v * base as f64 + d as f64;
1975 }
1976 return Some(exact.map_or(v, |e| e as f64));
1977 }
1978 None
1979}
1980
1981pub fn value_fits(p: &Parameter, v: &Value) -> bool {
1983 match p.param_type.as_str() {
1984 "string" => v.is_string(),
1985 "number" => v.as_f64().is_some_and(f64::is_finite),
1986 "integer" => v.as_f64().is_some_and(|f| f.is_finite() && f.fract() == 0.0),
1987 "boolean" => v.is_boolean(),
1988 "enum" => v.as_str().is_some_and(|s| p.values.as_ref().is_some_and(|vs| vs.iter().any(|x| x == s))),
1989 "list" => string_list(v),
1990 "url" => v.as_str().is_some_and(|s| RX.url.is_match(s)),
1991 "duration" => v.as_str().is_some_and(|s| RX.duration.is_match(s)),
1992 _ => false,
1993 }
1994}
1995
1996pub(crate) fn string_list(v: &Value) -> bool {
1998 matches!(v, Value::Array(list) if list.iter().all(Value::is_string))
1999}
2000
2001pub fn requires_of(r: &Reading) -> Vec<String> {
2005 fn walk(nodes: &[Node], out: &mut std::collections::BTreeSet<String>) {
2006 let set = |v: Option<&Value>| match v {
2007 Some(Value::String(s)) => !s.trim().is_empty(),
2008 Some(Value::Null) | None => false,
2009 Some(_) => true,
2010 };
2011 for n in nodes {
2012 if !n.is_directive() {
2013 continue;
2014 }
2015 if let Some(k) = crate::registry::kind(&n.kind)
2016 && !k.family.is_empty()
2017 {
2018 out.insert(k.family.clone());
2019 }
2020 if n.kind == "agent" && !set(n.attrs.get("protocol")) && !set(n.attrs.get("src")) && !set(n.attrs.get("endpoint")) {
2021 out.insert("agents".into());
2022 }
2023 if n.kind == "allowance" {
2024 out.insert("spending".into());
2025 }
2026 walk(n.children(), out);
2027 }
2028 }
2029 let mut out = std::collections::BTreeSet::new();
2030 walk(&r.document.body, &mut out);
2031 out.into_iter().collect()
2032}