Skip to main content

instruction_md/
read.rs

1//! The reader: source → the authored tree of §2 and the diagnostics of §18.
2//!
3//! One pass over the lines, with a stack of open directives (§4.2's precedence):
4//!  1. whole-document metadata — front matter on the first line, backmatter after a plain `---` separator (§3.1,
5//!     §3.2);
6//!  2. fenced code, the literal HTML blocks and `$$` display math suspend recognition, and comments are opaque until
7//!     closed, their bytes leaving the body (§3.3);
8//!  3. outside those, container and leaf directives at physical column zero (§5.1), each Markdown body read with the
9//!     same rules, a structured one kept as data (§7);
10//!  4. within Markdown, alerts, keyword rules and their reasons at the start of a line, of a list item or of a quoted
11//!     line (§6.1) — a keyword line interrupts the prose before it.
12//!
13//! Inline syntax (typed references, wiki-links, footnote references, math, `${…}`) stays in the Markdown nodes'
14//! source; [`crate::inline`] reads it.
15
16use 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
31/// How deeply directives may nest (a guard for hostile input: past it, an opener is prose, with a diagnostic).
32pub(crate) const MAX_NESTING: usize = 128;
33
34/// What a reading needs to know of its source.
35#[derive(Clone, Debug, Default)]
36pub struct ReadOptions {
37    /// A part of a document (an extension's fallback, a selected fragment), with no metadata regions.
38    pub fragment: bool,
39    /// The document's URI, which the tree carries.
40    pub uri: String,
41    /// A host's integrations policy (S34), read as if the document were served with it as its `host-integrations`:
42    /// what an editor knows of the workspace before the document is served. One in the front matter is read instead.
43    pub host: Option<PolicyLayer>,
44}
45
46/// A Markdown node that is parsed prose, in the order the reader made it: its text and where it stands.
47#[derive(Clone, Debug, PartialEq)]
48pub(crate) struct ProseRef {
49    pub(crate) source: String,
50    pub(crate) range: Option<Range>,
51}
52
53/// A document read: its tree and what the reader learned on the way.
54#[derive(Clone, Debug)]
55pub struct Reading {
56    pub document: Document,
57    /// The reader's diagnostics, in source order.
58    pub diagnostics: Vec<Diagnostic>,
59    /// The explicit identities (§5.3) in source order: directive and keyword ids, heading `{#id}`s.
60    pub identities: Vec<Identity>,
61    /// The declared parameters (§12), from the front matter and param leaves, in declaration order.
62    pub parameters: Vec<Parameter>,
63    /// The footnote labels defined in the document, and the line of their definition.
64    pub footnotes: BTreeMap<String, u32>,
65    /// The lines that held nothing but a comment (§3.3), which leave the body.
66    pub comments: BTreeSet<u32>,
67    /// The source's lines (a leading BOM removed).
68    pub lines: Vec<String>,
69    /// The front matter's lines: from the opening `---` (line 1) to the closing one, both included.
70    pub front_range: Option<Range>,
71    /// The backmatter's lines (§3.2): from its `---` separator line — a line of exactly `---` after a blank line,
72    /// at the top level, followed by a known backmatter key — to the source's last line. The separator is part of
73    /// the range, so the body ends on the line before `back_range.start` ([`split_backmatter`] cuts the text there).
74    pub back_range: Option<Range>,
75    /// The effective integrations policy (S34): the front matter's `host-integrations` (or [`ReadOptions::host`]) and
76    /// `integrations` merged; `None` when the document has neither, and for a fragment.
77    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    /// the source as given, and where each line starts in it
83    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    /// The source as it was given to [`read`] (a leading BOM included).
109    pub fn source(&self) -> &str {
110        &self.source
111    }
112
113    /// The byte offset in [`Reading::source`] at which a line (1-based) begins; the source's length past its last.
114    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    /// Does the agent text differ from the source? False when the text profile copies the document as written —
120    /// prose, and rules already in their canonical form (`MUST: …`), with no metadata, comment, block, typed
121    /// reference or parameter it rewrites — so a host may hand the source on unchanged; the agent text ends in one
122    /// newline, which alone is not a change, but a leading BOM or CRLF line endings are (the agent text has neither).
123    /// Diagnostics are not considered: check them as well ([`crate::check_reading`]).
124    ///
125    /// ```
126    /// use instruction_md::{read, ReadOptions};
127    ///
128    /// let o = ReadOptions::default();
129    /// assert!(!read("Plan the day.\n\nMUST: keep it short.", &o).changes_text());
130    /// assert!(read("**MUST:** keep it short.\n", &o).changes_text()); // the text is `MUST: keep it short.`
131    /// assert!(read("Plan the day. <!-- for Alex -->\n", &o).changes_text());
132    /// ```
133    pub fn changes_text(&self) -> bool {
134        self.text(None).trim_end_matches('\n') != self.source.trim_end_matches('\n')
135    }
136
137    /// The explicit identity, if the document has it.
138    pub fn identity(&self, id: &str) -> Option<&Identity> {
139        self.identity_index.get(id).and_then(|&i| self.identities.get(i))
140    }
141
142    /// The declared parameter, if the document declares it.
143    pub fn parameter(&self, name: &str) -> Option<&Parameter> {
144        self.parameter_index.get(name).and_then(|&i| self.parameters.get(i))
145    }
146
147    /// Does the reading have errors?
148    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
164// ---- line grammar ----
165
166pub(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    /// the literal HTML blocks (CommonMark's kinds 1 to 5): an opening (group 1) and its end
193    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
241/// Counts leading spaces and tabs, a tab as four.
242fn 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// ---- the reader ----
248
249#[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
283/// A rule, a reason or an alert being read: its lines so far.
284struct Unit {
285    kind: UnitKind,
286    /// the rule or the alert: its index in the frame's nodes
287    node: usize,
288    /// a reason's rule: its index in the frame's nodes
289    rule: Option<usize>,
290    lines: Vec<Line>,
291    /// a reason's lines as written, should it stay prose
292    original: Vec<Line>,
293    shape: Shape,
294    offset: usize,
295    blanks: Vec<Line>,
296    /// an alert's last line, which a lazy continuation line may follow only when it had text
297    last: String,
298}
299
300/// The scope a directive (or the document) opened.
301struct 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    /// a literal HTML block, until this
312    html_end: Option<usize>,
313    /// an HTML block, until a blank line
314    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
366/// Reads a document into its authored tree, with the reader's diagnostics, in source order.
367pub 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
385/// Where each line of a text begins (lines split as [`split_lines`] splits them).
386fn 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/// A document cut at its backmatter (§3.2).
407#[derive(Clone, Debug, PartialEq)]
408pub struct SplitBackmatter<'a> {
409    /// The text before the backmatter's `---` separator line, the front matter included; the whole text when there
410    /// is no backmatter.
411    pub before: &'a str,
412    /// The backmatter as written: its separator line and every line after it, to the end; `None` when there is none.
413    pub backmatter: Option<&'a str>,
414    /// Its lines ([`Reading::back_range`]): from the separator to the last line.
415    pub range: Option<Range>,
416    /// Its mapping (empty when there is none, or it is not a valid YAML mapping).
417    pub data: Object,
418    /// The reader's `invalid-metadata` diagnostics about it: an error here means `data` is not what the author wrote.
419    pub diagnostics: Vec<Diagnostic>,
420}
421
422/// Cuts a document at its backmatter, as the reader recognizes it (a `---` separator after a blank line at the top
423/// level, followed by a known backmatter key, never inside a fence or a container): for a host that wants the text
424/// without its record (to hand a folder of documents on, or to show the body alone). Reads the document to find it.
425///
426/// ```
427/// use instruction_md::split_backmatter;
428///
429/// let s = split_backmatter("MUST: be brief.\n\n---\nowners: [alex]\n");
430/// assert_eq!(s.before, "MUST: be brief.\n\n");
431/// assert_eq!(s.backmatter, Some("---\nowners: [alex]\n"));
432/// assert_eq!(s.range.map(|r| r.start), Some(3));
433/// assert_eq!(s.data["owners"][0], "alex");
434/// ```
435pub 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
447/// The lines of a text: split at LF, CRLF and CR, without a last empty line.
448pub(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
476/// Orders diagnostics by (source URI when by_uri,) start line, then code (§18).
477pub(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    /// A tool's `server=#id` (§10, S32): the document's `mcp` or `service` with that id. Another kind is
535    /// `reference-kind` (an error); an id nothing in the document has is `reference-optional` (a warning), unless the
536    /// document extends others: a base may hold it, and the resolver composes it. A qualified `#alias/id` is the
537    /// resolver's, and a server named outright is a target, not a reference.
538    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    /// Reads a metadata region: a YAML mapping (§3.1, §3.2), or empty with an invalid-metadata error.
579    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    // ---- the scope: a document body, a container's body, a list item's ----
594
595    fn scope(&mut self, lines: &[Line], o: ScopeOptions) -> Vec<Node> {
596        self.depth += 1;
597        // (past the nesting guard, a scope is prose: no rule items nest deeper)
598        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            // comments are opaque until closed; their bytes leave the body, and a line that was only a comment goes
636            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    // ---- prose ----
750
751    /// Takes a line of prose, reading it for heading identities and footnote definitions on the way in.
752    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    /// Flushes the frame's prose and readies it for a directive node.
805    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    /// Pushes a node into the frame (its index).
815    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    // ---- keyword rules, reasons and alerts (§6.1) ----
836
837    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        // the line's own text, or a list item's, or a quoted line's
865        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    /// The rule a keyword line opens, or none when its emphasis does not match (no rule, §6.1).
927    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    /// Does the line carry on the open rule, reason or alert?
977    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                        // a reason written under the item's text belongs to its rule
1028                        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                // a line: its paragraph, until a blank line or a line that starts something else
1062                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    // ---- directives (§5) ----
1132
1133    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; // `:::note words` is prose
1141            }
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                // a format the kind does not take is reported (check_directive) and leaves the default body
1248                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        // S28: a connected object's protocol is name[/versions] (§10)
1306        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        // S29: an allowance's own values (a ${parameter} is checked once it resolves)
1318        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                // (named by its allowance, so a host checking one finds its own)
1322                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            // the body: the lines after the opener, to the closer's (or, unclosed, to the end)
1359            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                        // data may be any JSON value; every other structured kind is a mapping
1419                        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    /// Takes a line inside a literal, structured or uninterpreted body: only its closing fence is read.
1452    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    // ---- metadata ----
1482
1483    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        // (a mapping, as checked above: anything else binds nothing)
1556        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", &params) {
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 &params {
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    // ---- identities ----
1668
1669    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
1714/// Takes a line inside code, a literal HTML block or display math.
1715fn 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
1723/// The literal HTML block a line opens (its index), and where its opening ends.
1724fn 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
1739// ---- helpers ----
1740
1741fn 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
1748/// Does this line start a block that ends a paragraph (CommonMark's interruptions, and a directive)?
1749pub(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
1763/// A keyword or reason line, which interrupts the rule before it (§6.1).
1764fn 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
1775/// Removes up to n columns of leading whitespace, tabs to their stops.
1776fn 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
1790/// §3.2 rule 2 — the first nonblank, non-comment line after the separator begins with a known key.
1791fn 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
1801/// The line that closes a `$$` region opened at li — before any closing fence: a formula cannot cross a directive
1802/// boundary.
1803fn 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/// What [`strip_comments`] leaves of a line.
1816#[derive(Clone, Debug, PartialEq, Eq)]
1817pub struct Stripped {
1818    /// The text left.
1819    pub text: String,
1820    /// A comment is still open after the line.
1821    pub still_open: bool,
1822    /// A comment opened on the line.
1823    pub opened: bool,
1824    /// Nothing but the comment (and whitespace) was on the line.
1825    pub only: bool,
1826}
1827
1828/// Removes comment bytes from one line (§3.3); `open`: a comment from an earlier line is still open. Comment-looking
1829/// text in a backtick code span stays.
1830pub 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            // a code span closes with a run of exactly the same length
1863            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
1917/// A value written as text (a command line's `name=value`) as its declared type reads it: a number, true or false,
1918/// a comma-separated list; the text itself for the other types, and where it does not read as its type
1919/// ([`value_fits`] then refuses it).
1920pub 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
1946/// ECMAScript's `Number(text)`; `None` where that is NaN.
1947fn 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
1981/// Does a value satisfy a parameter's declared type (§12)?
1982pub 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
1996/// A list whose members are all strings.
1997pub(crate) fn string_list(v: &Value) -> bool {
1998    matches!(v, Value::Array(list) if list.iter().all(Value::is_string))
1999}
2000
2001/// What an author attestation names as its capabilities: the families of the kinds a document uses, and, by name,
2002/// the host grants it needs — `agents` (an `agent` with no `protocol`, `src` or `endpoint`, one the host runs itself)
2003/// and `spending` (an `allowance`, S29). The port of the reference's `requiresOf`.
2004pub 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}