Skip to main content

nb_api/parser/
document.rs

1//! Public document model: kinds, partitions, accessors, iterators.
2
3use std::ops::Range;
4use std::path::PathBuf;
5
6use serde::{Deserialize, Serialize};
7
8use super::helpers::{parse_todo_state_from_title, tag_token_spans_in};
9
10/// Distinguishes the three document kinds recognized by the parser.
11///
12/// [`DocumentKind::Note`] is the default for `.md` files and any
13/// path whose extension is not `.todo.md` or `.bookmark.md`.
14///
15/// [`DocumentKind::Todo`] is for `.todo.md` files. The Todo
16/// [`TodoState`] is derived from the title line via
17/// [`NoteDocument::todo_state`].
18///
19/// [`DocumentKind::Bookmark`] is for `.bookmark.md` files.
20#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
21#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
22#[serde(rename_all = "lowercase")]
23pub enum DocumentKind {
24    Note,
25    Todo,
26    Bookmark,
27}
28
29/// The parsed checkbox state of a Todo title.
30///
31/// Surfaced via [`NoteDocument::todo_state`] as
32/// `Option<TodoState>`; `None` when the title has no checkbox
33/// marker (permissive acceptance).
34#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
35#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
36#[serde(rename_all = "lowercase")]
37pub enum TodoState {
38    Open,
39    Done,
40}
41
42/// How the parser determines the [`DocumentKind`] for an input.
43///
44/// [`ParseContext::FromPath`] infers from the file extension:
45/// `.todo.md` → Todo, `.bookmark.md` → Bookmark, `.md` (or other)
46/// → Note. The bare `.todo` extension (without `.md`) maps to
47/// Note deterministically — the `.todo` extension is a `show
48/// --type` classification only, not mutation-authoritative.
49///
50/// [`ParseContext::Explicit`] sets the kind directly, overriding
51/// any inference.
52#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
53#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
54#[serde(rename_all = "snake_case", tag = "kind")]
55pub enum ParseContext {
56    FromPath(PathBuf),
57    Explicit(DocumentKind),
58}
59
60/// A parsed `nb` note, todo, or bookmark.
61///
62/// `NoteDocument` owns the complete original source as
63/// `Vec<u8>`. The source is byte-identical to the input passed
64/// to [`parse`]. The kind-specific ownership partition is
65/// exposed via accessor methods (e.g., [`NoteDocument::title`],
66/// [`NoteDocument::body`], [`NoteDocument::url`]) and the
67/// [`NoteDocument::tag_token_spans`] view.
68///
69/// See the P1 specification for the full contract.
70#[derive(Debug, Clone, PartialEq, Eq)]
71pub struct NoteDocument {
72    pub(crate) source: Vec<u8>,
73    pub(crate) partition: Partition,
74}
75
76#[derive(Debug, Clone, PartialEq, Eq)]
77pub(crate) enum Partition {
78    Note(NotePartition),
79    Todo(TodoPartition),
80    Bookmark(BookmarkPartition),
81}
82
83#[derive(Debug, Clone, PartialEq, Eq)]
84pub(crate) struct NotePartition {
85    pub(crate) prefix_range: Range<usize>,
86    pub(crate) title_range: Option<Range<usize>>,
87    pub(crate) tags_prefix_range: Option<Range<usize>>,
88    pub(crate) separator_ranges: Vec<Range<usize>>,
89    pub(crate) body_ranges: Vec<Range<usize>>,
90}
91
92#[derive(Debug, Clone, PartialEq, Eq)]
93pub(crate) struct TodoPartition {
94    pub(crate) prefix_range: Range<usize>,
95    pub(crate) title_range: Option<Range<usize>>,
96    pub(crate) separator_ranges: Vec<Range<usize>>,
97    pub(crate) tag_section_range: Option<Range<usize>>,
98    pub(crate) body_ranges: Vec<Range<usize>>,
99}
100
101#[derive(Debug, Clone, PartialEq, Eq)]
102pub(crate) struct BookmarkPartition {
103    pub(crate) prefix_range: Range<usize>,
104    pub(crate) title_range: Option<Range<usize>>,
105    pub(crate) url_range: Option<Range<usize>>,
106    pub(crate) separator_ranges: Vec<Range<usize>>,
107    pub(crate) tag_section_range: Option<Range<usize>>,
108    pub(crate) body_ranges: Vec<Range<usize>>,
109}
110
111impl NoteDocument {
112    /// The original source bytes, byte-identical to the input
113    /// passed to [`parse`].
114    pub fn source(&self) -> &[u8] {
115        &self.source
116    }
117
118    /// Returns a slice into the retained `source` bytes,
119    /// byte-identical to the original input. Equivalent to
120    /// [`NoteDocument::source`].
121    pub fn emit(&self) -> &[u8] {
122        &self.source
123    }
124
125    /// Verify the ownership partition satisfies the P1
126    /// invariants: union covers `[0, source.len())` exactly,
127    /// ranges are pairwise disjoint, each range is half-open
128    /// and within bounds. Returns `Ok(())` on success or an
129    /// `Err(&'static str)` describing the first violation.
130    ///
131    /// Used by integration tests and by `parse` itself when
132    /// the `debug_assertions` cfg flag is enabled. Production
133    /// callers do not need to invoke this; it exists to surface
134    /// parser regressions during testing.
135    pub fn verify_partition(&self) -> Result<(), &'static str> {
136        let source_len = self.source.len();
137        let mut covered: Vec<(usize, usize)> = Vec::new();
138        let mut check = |r: &std::ops::Range<usize>,
139                         name: &str|
140         -> Result<(), &'static str> {
141            if r.start > r.end {
142                return Err("range not half-open (start > end)");
143            }
144            if r.end > source_len {
145                return Err("range extends past source.len()");
146            }
147            covered.push((r.start, r.end));
148            let _ = name;
149            Ok(())
150        };
151        match &self.partition {
152            Partition::Note(note) => {
153                check(&note.prefix_range, "prefix")?;
154                if let Some(r) = &note.title_range {
155                    check(r, "title")?;
156                }
157                if let Some(r) = &note.tags_prefix_range {
158                    check(r, "tags_prefix")?;
159                }
160                for r in &note.separator_ranges {
161                    check(r, "separator")?;
162                }
163                for r in &note.body_ranges {
164                    check(r, "body")?;
165                }
166            },
167            Partition::Todo(todo) => {
168                check(&todo.prefix_range, "prefix")?;
169                if let Some(r) = &todo.title_range {
170                    check(r, "title")?;
171                }
172                for r in &todo.separator_ranges {
173                    check(r, "separator")?;
174                }
175                if let Some(r) = &todo.tag_section_range {
176                    check(r, "tag_section")?;
177                }
178                for r in &todo.body_ranges {
179                    check(r, "body")?;
180                }
181            },
182            Partition::Bookmark(bookmark) => {
183                check(&bookmark.prefix_range, "prefix")?;
184                if let Some(r) = &bookmark.title_range {
185                    check(r, "title")?;
186                }
187                if let Some(r) = &bookmark.url_range {
188                    check(r, "url")?;
189                }
190                for r in &bookmark.separator_ranges {
191                    check(r, "separator")?;
192                }
193                if let Some(r) = &bookmark.tag_section_range {
194                    check(r, "tag_section")?;
195                }
196                for r in &bookmark.body_ranges {
197                    check(r, "body")?;
198                }
199            },
200        }
201        covered.sort_by_key(|&(s, _)| s);
202        // Adjacency check: ranges must touch end-to-end
203        // (previous.end == next.start) with no overlap AND no
204        // gap. A gap means a byte was not assigned to any
205        // partition region.
206        for window in covered.windows(2) {
207            if window[0].1 > window[1].0 {
208                return Err("ranges overlap");
209            }
210            if window[0].1 < window[1].0 {
211                return Err(
212                    "partition leaves a gap (internal unassigned bytes)",
213                );
214            }
215        }
216        if covered.first().map(|r| r.0) != Some(0) {
217            return Err("partition does not start at byte 0");
218        }
219        if covered.last().map(|r| r.1) != Some(source_len) {
220            return Err("partition does not cover to source.len()");
221        }
222        Ok(())
223    }
224
225    /// The [`DocumentKind`] of this document.
226    pub fn kind(&self) -> DocumentKind {
227        match &self.partition {
228            Partition::Note(_) => DocumentKind::Note,
229            Partition::Todo(_) => DocumentKind::Todo,
230            Partition::Bookmark(_) => DocumentKind::Bookmark,
231        }
232    }
233
234    /// For Todo documents, the parsed checkbox state. `None` for
235    /// non-Todo documents and for Todo documents whose title has
236    /// no `[ ]`/`[x]` prefix (permissive acceptance).
237    pub fn todo_state(&self) -> Option<TodoState> {
238        match &self.partition {
239            Partition::Todo(todo) => {
240                let title = todo.title_range.as_ref()?;
241                let line = self.source.get(title.start..title.end)?;
242                parse_todo_state_from_title(line)
243            },
244            _ => None,
245        }
246    }
247
248    /// The raw title line bytes (including trailing newline);
249    /// `None` if no valid ATX H1 title.
250    pub fn title(&self) -> Option<&[u8]> {
251        let range = self.title_range()?;
252        Some(&self.source[range])
253    }
254
255    /// `Option<Result<&str, std::str::Utf8Error>>` view of the
256    /// title. `None` for no title; `Some(Ok(_))` for valid UTF-8;
257    /// `Some(Err(_))` for invalid UTF-8.
258    pub fn title_str(&self) -> Option<Result<&str, std::str::Utf8Error>> {
259        self.title().map(std::str::from_utf8)
260    }
261
262    /// For Note documents, the raw tags prefix line bytes
263    /// (including trailing newline); `None` otherwise.
264    pub fn tags_prefix(&self) -> Option<&[u8]> {
265        let NotePartition {
266            tags_prefix_range, ..
267        } = match &self.partition {
268            Partition::Note(note) => note,
269            _ => return None,
270        };
271        Some(&self.source[tags_prefix_range.clone()?])
272    }
273
274    /// For Todo/Bookmark documents, the raw tags-section bytes
275    /// (the entire H2 Tags section including its trailing
276    /// newline); `None` otherwise.
277    pub fn tag_section(&self) -> Option<&[u8]> {
278        let range = self.tag_section_range()?;
279        Some(&self.source[range])
280    }
281
282    /// Iterator over tag token byte spans (`&[u8]`). Tokens come
283    /// from `tags_prefix_range` for Note documents and from
284    /// `tag_section_range` for Todo/Bookmark documents. Spans
285    /// reference bytes owned by the source.
286    pub fn tags(&self) -> TagsIter<'_> {
287        TagsIter {
288            doc: self,
289            token_spans: self.tag_token_spans().into_iter(),
290        }
291    }
292
293    /// Iterator yielding `Result<&str, std::str::Utf8Error>` per
294    /// tag token.
295    pub fn tags_str(&self) -> TagsStrIter<'_> {
296        TagsStrIter {
297            doc: self,
298            token_spans: self.tag_token_spans().into_iter(),
299        }
300    }
301
302    /// All tag token spans across the document. For Note,
303    /// tokens come from `tags_prefix_range`; for Todo/Bookmark,
304    /// from `tag_section_range`. Spans reference bytes owned by
305    /// the source and SHALL NOT themselves own bytes.
306    pub fn tag_token_spans(&self) -> Vec<Range<usize>> {
307        match &self.partition {
308            Partition::Note(note) => tag_token_spans_in(
309                &self.source,
310                note.tags_prefix_range.as_ref(),
311            ),
312            Partition::Todo(todo) => tag_token_spans_in(
313                &self.source,
314                todo.tag_section_range.as_ref(),
315            ),
316            Partition::Bookmark(bookmark) => tag_token_spans_in(
317                &self.source,
318                bookmark.tag_section_range.as_ref(),
319            ),
320        }
321    }
322
323    /// Body partition ranges in source order (half-open byte offsets).
324    pub fn body_ranges(&self) -> Vec<Range<usize>> {
325        match &self.partition {
326            Partition::Note(note) => note.body_ranges.clone(),
327            Partition::Todo(todo) => todo.body_ranges.clone(),
328            Partition::Bookmark(bookmark) => bookmark.body_ranges.clone(),
329        }
330    }
331
332    /// Iterator over body byte ranges (in source order).
333    pub fn body(&self) -> BodyFragments<'_> {
334        BodyFragments {
335            source: &self.source,
336            ranges: self.body_ranges().into_iter(),
337        }
338    }
339
340    /// Concatenated body fragment bytes in source order (fingerprint domain).
341    pub fn body_bytes(&self) -> Vec<u8> {
342        let mut out = Vec::new();
343        for fragment in self.body() {
344            out.extend_from_slice(fragment);
345        }
346        out
347    }
348
349    /// Title line byte range when present (includes trailing newline).
350    pub fn title_byte_range(&self) -> Option<Range<usize>> {
351        self.title_range()
352    }
353
354    /// Tags-prefix (Note) or tags-section (Todo/Bookmark) byte range.
355    pub fn tags_byte_range(&self) -> Option<Range<usize>> {
356        match &self.partition {
357            Partition::Note(note) => note.tags_prefix_range.clone(),
358            Partition::Todo(todo) => todo.tag_section_range.clone(),
359            Partition::Bookmark(bookmark) => {
360                bookmark.tag_section_range.clone()
361            },
362        }
363    }
364
365    /// For Bookmark documents, the raw URL line bytes (including
366    /// trailing newline); `None` for non-Bookmark documents or
367    /// Bookmarks without a `<URL>` line.
368    pub fn url(&self) -> Option<&[u8]> {
369        let BookmarkPartition { url_range, .. } = match &self.partition {
370            Partition::Bookmark(bookmark) => bookmark,
371            _ => return None,
372        };
373        url_range.as_ref().map(|r| &self.source[r.clone()])
374    }
375
376    /// `Option<Result<&str, std::str::Utf8Error>>` view of the
377    /// URL.
378    pub fn url_str(&self) -> Option<Result<&str, std::str::Utf8Error>> {
379        self.url().map(std::str::from_utf8)
380    }
381
382    fn title_range(&self) -> Option<Range<usize>> {
383        match &self.partition {
384            Partition::Note(note) => note.title_range.clone(),
385            Partition::Todo(todo) => todo.title_range.clone(),
386            Partition::Bookmark(bookmark) => bookmark.title_range.clone(),
387        }
388    }
389
390    fn tag_section_range(&self) -> Option<Range<usize>> {
391        match &self.partition {
392            Partition::Note(_) => None,
393            Partition::Todo(todo) => todo.tag_section_range.clone(),
394            Partition::Bookmark(bookmark) => {
395                bookmark.tag_section_range.clone()
396            },
397        }
398    }
399}
400
401/// Iterator over tag token byte slices.
402pub struct TagsIter<'a> {
403    doc: &'a NoteDocument,
404    token_spans: std::vec::IntoIter<Range<usize>>,
405}
406
407impl<'a> Iterator for TagsIter<'a> {
408    type Item = &'a [u8];
409    fn next(&mut self) -> Option<Self::Item> {
410        self.token_spans.next().map(|r| &self.doc.source[r])
411    }
412}
413
414/// Iterator over tag token string slices, surfacing UTF-8 errors.
415pub struct TagsStrIter<'a> {
416    doc: &'a NoteDocument,
417    token_spans: std::vec::IntoIter<Range<usize>>,
418}
419
420impl<'a> Iterator for TagsStrIter<'a> {
421    type Item = Result<&'a str, std::str::Utf8Error>;
422    fn next(&mut self) -> Option<Self::Item> {
423        self.token_spans
424            .next()
425            .map(|r| std::str::from_utf8(&self.doc.source[r]))
426    }
427}
428
429/// Iterator over body byte ranges.
430pub struct BodyFragments<'a> {
431    source: &'a [u8],
432    ranges: std::vec::IntoIter<Range<usize>>,
433}
434
435impl<'a> Iterator for BodyFragments<'a> {
436    type Item = &'a [u8];
437    fn next(&mut self) -> Option<Self::Item> {
438        self.ranges.next().map(|r| &self.source[r])
439    }
440}