Skip to main content

instruction_md/
text.rs

1//! The text profile `instruction-text/1` (§14.2): the agent's representation of a document. Every generated unit — a
2//! rule with its reason, a `### Label: Title` heading with its attribute line and children, an authored Markdown
3//! segment — is separated from the next by exactly one blank line; an authored segment is copied unchanged except
4//! that typed inline references read as `label (kind; target)`, annotations as their label, and parameters as their
5//! values. Metadata and comments are never instructional body. A resolved document adds its resolved references and
6//! its composition changes after the body.
7
8use std::collections::HashSet;
9use std::sync::LazyLock;
10
11use serde_json::{Map, Value};
12
13use crate::inline::{InlineToken, TokenType, inline_tokens};
14use crate::jcs::canonical_json;
15use crate::js::{JS_DOT, JS_SPACES, js_value, utf16_cmp};
16use crate::pattern::Pattern;
17use crate::read::Reading;
18use crate::registry::{self, PRESENTATION_ATTRS, is_rule, typed_reference};
19use crate::resolve::Provenance;
20use crate::types::{Attrs, Document, Identity, Node, Object, Parameter};
21
22/// Does the instance have the explicit id?
23pub type Known<'a> = &'a dyn Fn(&str, &str) -> bool;
24
25/// What the text profile knows of a tree beyond its body.
26#[derive(Clone, Default)]
27pub struct TextOptions<'a> {
28    /// Supplied parameter values; a declared default stands in for an absent one (§12).
29    pub params: Option<Object>,
30    /// The document's declarations ([`Reading::parameters`]).
31    pub parameters: Vec<Parameter>,
32    /// Only the Markdown nodes the reader marked as parsed prose ([`Node::is_prose`]) are normalized; others are
33    /// copied as written. False: every Markdown node outside an example, a verbatim body or a kind this registry does
34    /// not define is.
35    pub use_prose: bool,
36    /// The local identities ([`Reading::identities`]): a typed reference to a missing `#id` reads `[unresolved]`.
37    /// `None`: none is checked (an empty list: every `#id` is missing).
38    pub identities: Option<Vec<Identity>>,
39    /// For a resolved body: does the instance have the explicit id? A typed reference to `#id`, or to `#alias/id` in
40    /// an included or inherited instance, that names one it does not have reads `[unresolved]`.
41    pub known: Option<Known<'a>>,
42}
43
44/// An object or resource record a resolver enriched a reference with (§14.1).
45#[derive(Clone, Debug, PartialEq)]
46pub struct ReferenceRecord {
47    pub key: String,
48    pub kind: String,
49    pub label: String,
50    pub target: String,
51    /// resolved or unresolved
52    pub status: String,
53    pub data: Option<Value>,
54    pub source: String,
55    pub sha256: String,
56}
57
58impl ReferenceRecord {
59    pub fn to_json(&self) -> Value {
60        let mut m = Map::new();
61        m.insert("key".into(), self.key.clone().into());
62        m.insert("kind".into(), self.kind.clone().into());
63        m.insert("label".into(), self.label.clone().into());
64        m.insert("target".into(), self.target.clone().into());
65        m.insert("status".into(), self.status.clone().into());
66        if let Some(d) = &self.data {
67            m.insert("data".into(), d.clone());
68        }
69        if !self.source.is_empty() {
70            m.insert("source".into(), self.source.clone().into());
71        }
72        if !self.sha256.is_empty() {
73            m.insert("sha256".into(), self.sha256.clone().into());
74        }
75        Value::Object(m)
76    }
77}
78
79struct Rx {
80    param_ref: Pattern,
81    reference: Pattern,
82    ticks: Pattern,
83}
84
85static RX: LazyLock<Rx> = LazyLock::new(|| Rx {
86    param_ref: Pattern::must(r"\$\{([A-Za-z_][A-Za-z0-9_.-]*)\}"),
87    reference: Pattern::must(&format!(r#"(?:^|[ \t])ref=(?:"((?:[^"\\]|\\{JS_DOT})*)"|([^{JS_SPACES}{{}}"]+))"#)),
88    ticks: Pattern::must("`+"),
89});
90
91fn rule_label(kind: &str) -> &'static str {
92    match kind {
93        "must" | "always" => "MUST",
94        "never" => "NEVER",
95        "should" => "SHOULD",
96        "avoid" => "SHOULD NOT",
97        "may" => "MAY",
98        "guardrail" => "GUARDRAIL",
99        _ => "",
100    }
101}
102
103fn heading_label(kind: &str) -> Option<&'static str> {
104    match kind {
105        "policy" => Some("Policy"),
106        "instruction" => Some("Instruction"),
107        "context" => Some("Context"),
108        _ => None,
109    }
110}
111
112const UNIT_EXCLUDED: &[&str] = &["id", "title", "class", "style"];
113const RULE_EXCLUDED: &[&str] = &["id", "if", "because", "not", "class", "style"];
114pub(crate) const PATCHES: &[&str] = &["replace", "extend", "remove"];
115
116/// The text profile of a tree.
117pub fn to_text(doc: &Document, opts: &TextOptions) -> String {
118    text_of(&doc.body, &[], &[], opts)
119}
120
121impl Reading {
122    /// The text profile of the document read — the agent text — with its own declarations, prose and identities;
123    /// `params` are supplied parameter values.
124    pub fn text(&self, params: Option<&Object>) -> String {
125        to_text(
126            &self.document,
127            &TextOptions {
128                params: params.cloned(),
129                parameters: self.parameters.clone(),
130                use_prose: true,
131                identities: Some(self.identities.clone()),
132                known: None,
133            },
134        )
135    }
136}
137
138struct Ctx<'o, 'a> {
139    o: &'o TextOptions<'a>,
140    identities: Option<HashSet<String>>,
141}
142
143pub(crate) fn text_of(body: &[Node], records: &[ReferenceRecord], provenance: &[Provenance], o: &TextOptions) -> String {
144    let ctx = Ctx { o, identities: o.identities.as_ref().map(|ids| ids.iter().map(|i| i.id.clone()).collect()) };
145    let mut text = units(body, &ctx).join("\n\n");
146    if !records.is_empty() {
147        let mut sorted: Vec<&ReferenceRecord> = records.iter().collect();
148        sorted.sort_by(|a, b| utf16_cmp(&a.key, &b.key));
149        let fenced: Vec<String> = sorted.iter().map(|r| fence(&canonical_json(&r.to_json()), "json")).collect();
150        text.push_str("\n\n### Resolved references\n\n");
151        text.push_str(&fenced.join("\n\n"));
152    }
153    let changes: Vec<String> = provenance
154        .iter()
155        .filter(|p| PATCHES.contains(&p.operation.as_str()))
156        .map(|p| {
157            let mut change = format!("- {} {} (origin: {})", p.operation, p.target, p.uri);
158            if !p.reason.is_empty() {
159                change.push_str(" — ");
160                change.push_str(&p.reason);
161            }
162            change
163        })
164        .collect();
165    if !changes.is_empty() {
166        text.push_str("\n\n### Composition changes\n\n");
167        text.push_str(&changes.join("\n"));
168    }
169    format!("{}\n", text.trim_end_matches('\n'))
170}
171
172fn units(nodes: &[Node], c: &Ctx) -> Vec<String> {
173    nodes.iter().map(|n| if n.is_markdown() { markdown_unit(n, c) } else { directive_unit(n, c) }).filter(|u| !u.is_empty()).collect()
174}
175
176fn markdown_unit(n: &Node, c: &Ctx) -> String {
177    if !c.o.use_prose || n.prose {
178        let instance = if n.instance.is_empty() { "root" } else { &n.instance };
179        return trim_lf(&normalize(&n.source, c, instance)).to_string();
180    }
181    trim_lf(&n.source).to_string()
182}
183
184/// A body copied as written — an example's, a verbatim one, or a kind this registry does not define (its fallback).
185pub(crate) fn literal(n: &Node) -> bool {
186    n.kind == "example" || n.attrs.get("verbatim") == Some(&Value::Bool(true)) || registry::kind(&n.kind).is_none()
187}
188
189fn raw_children(n: &Node) -> String {
190    let s: String = n.children().iter().filter(|c| c.is_markdown()).map(|c| c.source.as_str()).collect();
191    trim_lf(&s).to_string()
192}
193
194fn directive_unit(n: &Node, c: &Ctx) -> String {
195    let a = &n.attrs;
196    let children = || if literal(n) { raw_children(n) } else { units(n.children(), c).join("\n\n") };
197    if is_rule(&n.kind) {
198        let mut label = rule_label(&n.kind).to_string();
199        if n.kind == "should" && a.get("not") == Some(&Value::Bool(true)) {
200            label = "SHOULD NOT".into();
201        }
202        if let Some(Value::String(cond)) = a.get("if") {
203            label = format!("{label} (if {})", interpolate(cond, c.o));
204        }
205        let mut t = format!("{label}: {}", children());
206        if let Some(Value::String(because)) = a.get("because") {
207            t.push_str("\nBECAUSE: ");
208            t.push_str(&interpolate(because, c.o));
209        }
210        let rest = attribute_line(a, RULE_EXCLUDED, &[]);
211        if !rest.is_empty() {
212            t.push('\n');
213            t.push_str(&rest);
214        }
215        return t;
216    }
217    let label = if n.kind == "example" && a.get("avoid") == Some(&Value::Bool(true)) {
218        "Counterexample".to_string()
219    } else if n.kind == "example" {
220        "Example".to_string()
221    } else if let Some(h) = heading_label(&n.kind) {
222        h.to_string()
223    } else {
224        n.kind.clone()
225    };
226    let title = match (a.get("title"), a.get("id")) {
227        (Some(Value::String(t)), _) if !t.is_empty() => t.clone(),
228        (_, Some(Value::String(id))) => id.clone(),
229        _ => n.kind.clone(),
230    };
231    let mut parts = vec![format!("### {label}: {title}")];
232    let more: &[&str] = if n.kind == "example" {
233        &["avoid"]
234    } else if registry::kind(&n.kind).is_some_and(|k| k.family == "layout") {
235        PRESENTATION_ATTRS
236    } else {
237        &[]
238    };
239    // (S29 §6: an allowance's limits in one fixed sentence, its amounts as they resolved)
240    let line = if n.kind == "allowance" {
241        // (a reader's text, unresolved, gives an allowance's ${parameters} their declared values, as it does prose's)
242        let mut amounts = a.clone();
243        for k in ["max", "budget", "approve-above", "times", "from", "until", "currency", "per"] {
244            if let Some(Value::String(v)) = a.get(k) {
245                amounts.insert(k.into(), Value::String(interpolate(v, c.o)));
246            }
247        }
248        crate::allowance::sentence(&amounts, a.get("title").and_then(Value::as_str), a.get("id").and_then(Value::as_str))
249    } else {
250        attribute_line(a, UNIT_EXCLUDED, more)
251    };
252    if !line.is_empty() {
253        parts.push(line);
254    }
255    if let Some(v) = &n.value {
256        parts.push(fence(&v.source, &v.format));
257    } else if n.kind == "example" {
258        parts.push(fence(&raw_children(n), "markdown"));
259    } else {
260        let c = children();
261        if !c.is_empty() {
262            parts.push(c);
263        }
264    }
265    parts.join("\n\n")
266}
267
268/// `Attributes: {…}` in RFC 8785 form, or "" when nothing meaningful is left.
269fn attribute_line(a: &Attrs, excluded: &[&str], more: &[&str]) -> String {
270    let kept: Map<String, Value> = a
271        .iter()
272        .filter(|(k, _)| !excluded.contains(&k.as_str()) && !more.contains(&k.as_str()))
273        .map(|(k, v)| (k.clone(), v.clone()))
274        .collect();
275    if kept.is_empty() {
276        return String::new();
277    }
278    format!("Attributes: {}", canonical_json(&Value::Object(kept)))
279}
280
281/// Puts literal text in a code fence: a backtick run longer than any inside it, at least three.
282fn fence(text: &str, lang: &str) -> String {
283    let longest = RX.ticks.find_iter(text).iter().map(|(a, b)| b - a).max().unwrap_or(0);
284    let marker = "`".repeat(3.max(longest + 1));
285    let body = if text.ends_with('\n') { text.to_string() } else { format!("{text}\n") };
286    format!("{marker}{lang}\n{body}{marker}")
287}
288
289fn trim_lf(s: &str) -> &str {
290    s.trim_matches('\n')
291}
292
293// ---- prose: typed references, annotations and parameters ----
294
295/// A Markdown source with its inline forms in their text representation (§14.2 table).
296fn normalize(source: &str, c: &Ctx, instance: &str) -> String {
297    let tokens = inline_tokens(source);
298    rewrite(source, 0, source.len(), &tokens, None, c, instance)
299}
300
301/// Writes source[from..to] with the tokens inside it in their text form; skip is a token not to rewrite (the
302/// directive whose label this is).
303fn rewrite(source: &str, from: usize, to: usize, tokens: &[InlineToken], skip: Option<usize>, c: &Ctx, instance: &str) -> String {
304    let mut out = String::new();
305    let mut at = from;
306    for (i, t) in tokens.iter().enumerate() {
307        // nested inside one already rewritten, or outside this range
308        if Some(i) == skip || t.start < at || t.end > to {
309            continue;
310        }
311        out.push_str(&source[at..t.start]);
312        out.push_str(&token_text(source, tokens, i, c, instance));
313        at = t.end;
314    }
315    out.push_str(&source[at..to]);
316    out
317}
318
319fn token_text(source: &str, tokens: &[InlineToken], i: usize, c: &Ctx, instance: &str) -> String {
320    let t = &tokens[i];
321    let written = &source[t.start..t.end];
322    match t.token_type {
323        TokenType::Param => return param_text(&t.name, c.o).unwrap_or_else(|| written.to_string()),
324        TokenType::Directive => {}
325        _ => return written.to_string(),
326    }
327    let label = rewrite(source, t.label_start, t.label_end, tokens, Some(i), c, instance);
328    if typed_reference(&t.kind) || t.kind == "ref" || t.kind == "cite" {
329        let Some(target) = ref_of(t.attributes.as_deref()) else {
330            return written.to_string();
331        };
332        let mut text = format!("{label} ({}; {target})", t.kind);
333        if unresolved_target(&target, c, instance) {
334            text.push_str(" [unresolved]");
335        }
336        return text;
337    }
338    label
339}
340
341/// A local target (#id, or #alias/id in a composed instance) that the document does not have.
342fn unresolved_target(target: &str, c: &Ctx, instance: &str) -> bool {
343    let Some(rest) = target.strip_prefix('#') else { return false };
344    let path: Vec<&str> = rest.split('/').collect();
345    let id = path[path.len() - 1];
346    let path = &path[..path.len() - 1];
347    if let Some(known) = c.o.known {
348        let mut within = instance.to_string();
349        if !path.is_empty() {
350            within.push('/');
351            within.push_str(&path.join("/"));
352        }
353        return !known(&within, id);
354    }
355    c.identities.as_ref().is_some_and(|ids| path.is_empty() && !ids.contains(id))
356}
357
358/// The ref attribute an inline directive's attribute list holds.
359fn ref_of(attributes: Option<&str>) -> Option<String> {
360    let attributes = attributes.filter(|a| !a.is_empty())?;
361    let m = RX.reference.captures(attributes)?;
362    if let Some(quoted) = m.get(attributes, 1) {
363        return serde_json::from_str::<String>(&format!("\"{quoted}\"")).ok();
364    }
365    m.get(attributes, 2).map(str::to_string)
366}
367
368/// A parameter's value as text; `None` to leave `${name}` as written (§12).
369fn param_text(name: &str, o: &TextOptions) -> Option<String> {
370    if let Some(v) = o.params.as_ref().and_then(|p| p.get(name)) {
371        return value_text(v);
372    }
373    o.parameters.iter().find(|p| p.name == name).and_then(|p| p.default.as_ref()).and_then(value_text)
374}
375
376/// How a value reads in text (§12): strings and list items with their Markdown punctuation escaped, booleans and
377/// numbers as JSON scalars, lists joined with ", "; `None` for no value (null).
378pub fn value_text(value: &Value) -> Option<String> {
379    match value {
380        Value::Null => None,
381        Value::Array(list) => Some(list.iter().map(|x| escape_value(&js_value(Some(x)))).collect::<Vec<_>>().join(", ")),
382        Value::String(s) => Some(escape_value(s)),
383        v => Some(canonical_json(v)),
384    }
385}
386
387/// Substitutes parameters in a rule's condition or reason: the same values, as data.
388fn interpolate(s: &str, o: &TextOptions) -> String {
389    RX.param_ref.replace_all(s, |m| {
390        let whole = m.get(s, 0).unwrap_or("");
391        let name = m.get(s, 1).unwrap_or("");
392        param_text(name, o).unwrap_or_else(|| whole.to_string())
393    })
394}
395
396/// Substitutes parameters with values (a resolution's), as data.
397pub(crate) fn interpolate_values(s: &str, values: &Object) -> String {
398    RX.param_ref.replace_all(s, |m| {
399        let whole = m.get(s, 0).unwrap_or("");
400        let name = m.get(s, 1).unwrap_or("");
401        values.get(name).and_then(value_text).unwrap_or_else(|| whole.to_string())
402    })
403}
404
405/// A value inserts data, never syntax — the punctuation that could open Markdown or Instruction forms is escaped.
406fn escape_value(v: &str) -> String {
407    let mut out = String::with_capacity(v.len());
408    for c in v.chars() {
409        if "\\`*_{}[]<>|~$".contains(c) {
410            out.push('\\');
411        }
412        out.push(c);
413    }
414    out
415}