krz/orgo

  1//! RESOLVE stage (spec §2.1, §4.3): rewrite `LinkTarget`s to final URLs using the
  2//! symbol table, AND record which targets each page consumed.
  3//!
  4//! Critical invariant (spec §4.3, R2): RESOLVE returns the used-target list as a
  5//! first-class side output from v1, even before incrementality consumes it. Throwing
  6//! it away would make renamed-heading invalidation impossible to compute later without
  7//! re-resolving everything.
  8//!
  9//! Resolution rewrites each internal link into an [`crate::model::LinkTarget::External`]
 10//! carrying its final URL, so the renderer needs no symbol-table knowledge. Unresolved
 11//! links are left untouched (the renderer falls back to a best-effort anchor) and
 12//! reported as [`BrokenLink`] warnings (spec §4.3.4).
 13
 14use camino::Utf8Path;
 15
 16use crate::index::{SymbolTable, TargetId};
 17use crate::model::{Document, Element, Link, LinkTarget, Object, Section, TableRow};
 18use crate::util::{normalize_link_path, output_url};
 19
 20/// A document whose links have been rewritten to concrete URLs.
 21#[derive(Debug, Clone)]
 22pub struct ResolvedDoc {
 23    pub document: Document,
 24}
 25
 26/// A broken internal link — surfaced as a warning, or an error under `--strict` (spec §4.3.4).
 27#[derive(Debug, Clone)]
 28pub struct BrokenLink {
 29    pub target: TargetId,
 30}
 31
 32/// Result of resolving one page. `used_targets` are the "uses" edges (spec §4.3).
 33#[derive(Debug)]
 34pub struct ResolveOutput {
 35    pub resolved: ResolvedDoc,
 36    /// The "uses" edges — MUST be captured from day one (spec §4.3, R2).
 37    pub used_targets: Vec<TargetId>,
 38    pub broken: Vec<BrokenLink>,
 39}
 40
 41/// `resolve(doc, &SymbolTable) -> (ResolvedDoc, Vec<TargetId used>)` (spec §4.3).
 42pub fn resolve(doc: &Document, symbols: &SymbolTable) -> ResolveOutput {
 43    let mut document = doc.clone();
 44    let from = doc.source_path.clone();
 45    let mut used = Vec::new();
 46    let mut broken = Vec::new();
 47    let mut cx = Cx {
 48        from: &from,
 49        symbols,
 50        used: &mut used,
 51        broken: &mut broken,
 52    };
 53    cx.section(&mut document.root);
 54    ResolveOutput {
 55        resolved: ResolvedDoc { document },
 56        used_targets: used,
 57        broken,
 58    }
 59}
 60
 61/// The text a description-less internal link should display once its target becomes a URL.
 62fn human_text(target: &LinkTarget) -> Option<String> {
 63    match target {
 64        LinkTarget::Heading(t) => Some(t.clone()),
 65        LinkTarget::CustomId(id) | LinkTarget::Id(id) => Some(id.clone()),
 66        LinkTarget::File { path, .. } => Some(path.to_string()),
 67        LinkTarget::External(_) => None,
 68    }
 69}
 70
 71struct Cx<'a> {
 72    from: &'a Utf8Path,
 73    symbols: &'a SymbolTable,
 74    used: &'a mut Vec<TargetId>,
 75    broken: &'a mut Vec<BrokenLink>,
 76}
 77
 78impl Cx<'_> {
 79    fn section(&mut self, section: &mut Section) {
 80        if let Some(h) = &mut section.heading {
 81            self.objects(&mut h.title);
 82        }
 83        for el in &mut section.content {
 84            self.element(el);
 85        }
 86        for child in &mut section.children {
 87            self.section(child);
 88        }
 89    }
 90
 91    fn element(&mut self, el: &mut Element) {
 92        match el {
 93            Element::Paragraph(objs) => self.objects(objs),
 94            Element::List(list) => {
 95                for item in &mut list.items {
 96                    if let Some(term) = &mut item.term {
 97                        self.objects(term);
 98                    }
 99                    for e in &mut item.content {
100                        self.element(e);
101                    }
102                }
103            }
104            Element::Table(table) => {
105                for row in &mut table.rows {
106                    if let TableRow::Cells(cells) = row {
107                        for cell in cells {
108                            self.objects(cell);
109                        }
110                    }
111                }
112            }
113            Element::QuoteBlock(inner)
114            | Element::CenterBlock(inner)
115            | Element::Drawer { content: inner, .. }
116            | Element::FootnoteDefinition { content: inner, .. } => {
117                for e in inner {
118                    self.element(e);
119                }
120            }
121            _ => {}
122        }
123    }
124
125    fn objects(&mut self, objs: &mut [Object]) {
126        for obj in objs {
127            match obj {
128                Object::Link(link) => self.link(link),
129                Object::Bold(i)
130                | Object::Italic(i)
131                | Object::Underline(i)
132                | Object::StrikeThrough(i) => self.objects(i),
133                Object::FootnoteRef {
134                    inline: Some(i), ..
135                } => self.objects(i),
136                _ => {}
137            }
138        }
139    }
140
141    fn link(&mut self, link: &mut Link) {
142        if let Some(desc) = &mut link.description {
143            self.objects(desc);
144        }
145        let tid = match &link.target {
146            LinkTarget::External(_) => return,
147            LinkTarget::CustomId(id) => TargetId::CustomId(id.clone()),
148            LinkTarget::Id(id) => TargetId::Id(id.clone()),
149            LinkTarget::Heading(t) => TargetId::Heading(t.clone()),
150            LinkTarget::File { path, .. } => {
151                TargetId::File(normalize_link_path(self.from, path))
152            }
153        };
154        match self.symbols.targets.get(&tid) {
155            Some(loc) => {
156                self.used.push(tid.clone());
157                // Preserve the human-readable text before the target becomes a bare URL,
158                // so a description-less `[[*Heading]]` still renders as the heading text.
159                if link.description.is_none() {
160                    if let Some(text) = human_text(&link.target) {
161                        link.description = Some(vec![Object::Text(text)]);
162                    }
163                }
164                let url = output_url(self.from, &loc.source_path, loc.anchor.as_deref());
165                link.target = LinkTarget::External(url);
166            }
167            None => {
168                self.broken.push(BrokenLink { target: tid });
169                // Leave the original target for the renderer's best-effort fallback.
170            }
171        }
172    }
173}