1use 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
22pub type Known<'a> = &'a dyn Fn(&str, &str) -> bool;
24
25#[derive(Clone, Default)]
27pub struct TextOptions<'a> {
28 pub params: Option<Object>,
30 pub parameters: Vec<Parameter>,
32 pub use_prose: bool,
36 pub identities: Option<Vec<Identity>>,
39 pub known: Option<Known<'a>>,
42}
43
44#[derive(Clone, Debug, PartialEq)]
46pub struct ReferenceRecord {
47 pub key: String,
48 pub kind: String,
49 pub label: String,
50 pub target: String,
51 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
116pub fn to_text(doc: &Document, opts: &TextOptions) -> String {
118 text_of(&doc.body, &[], &[], opts)
119}
120
121impl Reading {
122 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
184pub(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 let line = if n.kind == "allowance" {
241 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
268fn 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
281fn 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
293fn 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
301fn 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 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
341fn 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
358fn 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
368fn 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
376pub 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
387fn 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
396pub(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
405fn 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}