Skip to main content

docextract/
lib.rs

1#![doc = include_str!("../README.md")]
2#![allow(clippy::doc_markdown)]
3
4mod pattern;
5
6use crate::pattern::{Pattern, PatternError};
7use std::collections::{HashMap, HashSet};
8use std::io::{self, BufWriter, Read, Write};
9use std::ops::Range;
10use std::path::{Path, PathBuf};
11use std::rc::Rc;
12
13/// Holds all parsed entries, their file-to-range mappings, and a global
14/// tag interning pool shared across all `Docextract` instances on this thread.
15struct Cache {
16    /// Global tag interner. Tags are interned via `Rc<str>` so identical
17    /// tag names across different parse calls share the same allocation.
18    tags: HashSet<Rc<str>>,
19
20    /// All parsed `DocEntry` records from all files, stored contiguously.
21    /// A file's entries span `entries[ranges[path].start .. ranges[path].end]`.
22    entries: Vec<DocEntry>,
23
24    /// Maps a canonical path to the range of its entries in `entries`.
25    /// The presence of a key is the cache-hit test — `contains_key()` is O(1).
26    ranges: HashMap<PathBuf, Range<usize>>,
27}
28
29thread_local! {
30    /// Thread-local global cache. Each OS thread gets its own independent
31    /// cache. Within a single thread (the normal build-script case), all
32    /// `Docextract` instances share this cache transparently.
33    static CACHE: std::cell::RefCell<Cache> = std::cell::RefCell::new(Cache {
34        tags: HashSet::new(),
35        entries: Vec::new(),
36        ranges: HashMap::new(),
37    });
38}
39
40/// Normalize a path for use as a cache key.
41///
42/// Uses `canonicalize()` to resolve `.`, `..`, and symlinks.
43/// The sentinel `"-"` (stdin) is returned as-is.
44fn normalize_path(path: &Path) -> io::Result<PathBuf> {
45    if path == Path::new("-") {
46        return Ok(PathBuf::from("-"));
47    }
48    path.canonicalize()
49}
50
51/// Intern a tag name into the global interning pool.
52fn intern_tag(pool: &mut HashSet<Rc<str>>, name: &str) -> Rc<str> {
53    if let Some(existing) = pool.get(name) {
54        return Rc::clone(existing);
55    }
56    let rc: Rc<str> = Rc::from(name.to_string());
57    pool.insert(Rc::clone(&rc));
58    rc
59}
60
61/// Internal enum for the output destination: file or stdout.
62///
63/// Implements `Write` by dispatching to the appropriate variant.
64enum OutputTarget {
65    File(std::fs::File),
66    Stdout(std::io::Stdout),
67}
68
69impl Write for OutputTarget {
70    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
71        match self {
72            OutputTarget::File(f) => f.write(buf),
73            OutputTarget::Stdout(s) => s.write(buf),
74        }
75    }
76
77    fn flush(&mut self) -> io::Result<()> {
78        match self {
79            OutputTarget::File(f) => f.flush(),
80            OutputTarget::Stdout(s) => s.flush(),
81        }
82    }
83}
84
85/// A single parsed documentation entry.
86struct DocEntry {
87    /// Tag name — interned via Rc<str> so identical tags share one allocation.
88    tag: Rc<str>,
89    /// Line content — includes trailing newline (\n or \r\n) or empty at EOF.
90    text: Box<str>,
91    /// `true` if this entry was created from a transient tag directive
92    /// (`////tagname text`). Transient entries are skipped in unfiltered mode.
93    transient: bool,
94}
95
96/// Builder for extracting `////` documentation from multiple sources into a
97/// single output file.
98///
99/// Created via `Docextract::new(output_path)`. If the output path is `"-"`,
100/// writes to stdout.
101///
102/// Each `.input()` call processes a file immediately via parse-then-filter.
103/// Output from multiple files is concatenated in call order with no separator
104/// between files.
105///
106/// Automatically detects build-script context: if `OUT_DIR` is set at
107/// construction time, `cargo:rerun-if-changed` directives are emitted
108/// for each file processed by `.input()`.
109pub struct Docextract {
110    output: Option<BufWriter<OutputTarget>>,
111    rerun_if_changed: bool,
112    output_filter: Option<Pattern>,
113}
114
115/// Extract the initial tag from a file path (filename without extension).
116fn path_stem(path: &Path) -> String {
117    path.file_stem()
118        .and_then(|s| s.to_str())
119        .unwrap_or("unknown")
120        .to_string()
121}
122
123impl From<PatternError> for io::Error {
124    fn from(e: PatternError) -> io::Error {
125        io::Error::new(io::ErrorKind::InvalidInput, e.to_string())
126    }
127}
128
129impl Docextract {
130    /// Create a new builder, writing extracted documentation to `output`.
131    ///
132    /// If `output` is `"-"`, writes to stdout. Otherwise creates or truncates
133    /// the file at the given path.
134    ///
135    /// The output is wrapped in a 32 KiB `BufWriter` for efficient I/O.
136    ///
137    /// **Auto-detection**: If `std::env::var("OUT_DIR")` is set (indicating
138    /// a build script context), `rerun_if_changed` is initialized to `true`.
139    pub fn new(output: impl AsRef<Path>) -> io::Result<Self> {
140        let target = if output.as_ref() == Path::new("-") {
141            OutputTarget::Stdout(std::io::stdout())
142        } else {
143            OutputTarget::File(std::fs::File::create(output.as_ref())?)
144        };
145
146        let writer = BufWriter::with_capacity(32768, target);
147
148        let rerun_if_changed = std::env::var("OUT_DIR").is_ok();
149
150        Ok(Docextract {
151            output: Some(writer),
152            rerun_if_changed,
153            output_filter: None,
154        })
155    }
156
157    /// Extract documentation from a file at `path`.
158    ///
159    /// On first access, reads the entire file, parses it into `DocEntry`
160    /// records, and caches them. Subsequent accesses use the cache.
161    /// Emits only persistent entries in unfiltered mode (transient skipped).
162    ///
163    /// # Error Handling
164    ///
165    /// - **File not found**: prints a warning to stderr and returns `Ok`.
166    /// - **Other I/O errors**: returns `Err(io::Error)`.
167    pub fn input(&mut self, path: impl AsRef<Path>) -> io::Result<&mut Self> {
168        if self.output.is_none() {
169            return Err(io::Error::new(
170                io::ErrorKind::BrokenPipe,
171                "output already closed",
172            ));
173        }
174        self.input_impl(path.as_ref(), None)
175    }
176
177    /// Extract documentation from stdin.
178    ///
179    /// Reads all of stdin, parses it into `DocEntry` records, and caches them
180    /// under the key `"-"`. Subsequent calls use the cache.
181    ///
182    /// Without filters: emits only persistent entries (transient skipped).
183    pub fn stdin(&mut self) -> io::Result<&mut Self> {
184        if self.output.is_none() {
185            return Err(io::Error::new(
186                io::ErrorKind::BrokenPipe,
187                "output already closed",
188            ));
189        }
190        self.stdin_impl()
191    }
192
193    /// Set the output filter pattern.
194    ///
195    /// Only doc lines whose tag matches this pattern will be emitted.
196    /// Applies to all subsequent `.input()`, `.input_filtered()`, and `.stdin()` calls.
197    ///
198    /// Pass `None` to clear the filter.
199    ///
200    /// # Errors
201    ///
202    /// Only on the `regex`-enabled path: returns
203    /// `Err(PatternError::InvalidSyntax(...))` if the pattern string is a
204    /// malformed regex. On the no-regex path this method never fails.
205    pub fn filter_output(&mut self, filter: Option<&str>) -> Result<&mut Self, PatternError> {
206        self.output_filter = match filter {
207            Some(s) => Some(Pattern::new(s)?),
208            None => None,
209        };
210        Ok(self)
211    }
212
213    /// Extract documentation from a file at `path`, applying an input filter
214    /// pattern to tag names. Only `DocEntry` items whose tag matches `filter`
215    /// are emitted. Transient entries ARE included when a filter is active.
216    ///
217    /// On first access to a given path, reads the entire file, parses it into
218    /// `Vec<DocEntry>`, and stores it in the cache. Subsequent
219    /// `.input_filtered()` or `.input()` calls for the same path use the
220    /// cached entries.
221    ///
222    /// `.input_filtered("-", filter)` is supported: reads stdin, caches under
223    /// key `"-"`, and filters by tag.
224    ///
225    /// # Errors
226    ///
227    /// - Pattern compile errors are converted to `io::Error` with
228    ///   `ErrorKind::InvalidInput` via `From<PatternError> for io::Error`.
229    /// - File-access errors: file not found → warning to stderr + `Ok`;
230    ///   other I/O errors → `Err(io::Error)`.
231    /// - Invalid UTF-8 in file content → `Err(io::ErrorKind::InvalidData)`.
232    pub fn input_filtered(
233        &mut self,
234        path: impl AsRef<Path>,
235        filter: &str,
236    ) -> io::Result<&mut Self> {
237        if self.output.is_none() {
238            return Err(io::Error::new(
239                io::ErrorKind::BrokenPipe,
240                "output already closed",
241            ));
242        }
243        let pattern = Pattern::new(filter)?;
244        self.input_impl(path.as_ref(), Some(&pattern))
245    }
246
247    /// Finalize extraction: flush and close the output writer.
248    ///
249    /// Returns `&mut self` so that the call is chainable: an idiomatic
250    /// one-liner is `Docextract::new(...)?.input(...)?.done()?;`.
251    ///
252    /// After calling `done()`, the output is closed and further `.input()`
253    /// or `.stdin()` calls will error with `BrokenPipe`. Calling `done()`
254    /// multiple times is safe (idempotent — subsequent calls are no-ops).
255    pub fn done(&mut self) -> io::Result<&mut Self> {
256        self.close_output()?;
257        Ok(self)
258    }
259
260    /// Control whether `cargo:rerun-if-changed` is emitted from `.input()`.
261    pub fn rerun_if_changed(&mut self, value: bool) -> &mut Self {
262        self.rerun_if_changed = value;
263        self
264    }
265
266    /// Clear the thread-local global parse cache.
267    ///
268    /// Drops all cached `DocEntry` records, interned tags, and file-to-range
269    /// mappings. Subsequent `.input()` calls will re-read and re-parse files
270    /// from disk. Useful between build phases or at the end of a script to
271    /// free memory.
272    ///
273    /// This is a free function (associated function, not a method) — no
274    /// instance is required.
275    ///
276    /// # Examples
277    ///
278    /// ```rust
279    /// # use docextract::Docextract;
280    /// # use std::io;
281    /// # fn example() -> io::Result<()> {
282    /// // Phase 1: parse several files into cache
283    /// Docextract::new("phase1.md")?.input("src/a.rs")?.done()?;
284    ///
285    /// // Clear cache between phases to free memory
286    /// Docextract::clear_cache();
287    ///
288    /// // Phase 2: re-parse from scratch
289    /// Docextract::new("phase2.md")?.input("src/b.rs")?.done()?;
290    /// # Ok(())
291    /// # }
292    /// ```
293    pub fn clear_cache() {
294        CACHE.with(|c| {
295            *c.borrow_mut() = Cache {
296                tags: HashSet::new(),
297                entries: Vec::new(),
298                ranges: HashMap::new(),
299            };
300        });
301    }
302
303    // --- private methods ---
304
305    /// Emit entries to the output writer, applying filters and transient exclusion.
306    fn emit_entries(
307        &mut self,
308        entries: &[DocEntry],
309        input_filter: Option<&Pattern>,
310        any_filter_active: bool,
311    ) -> io::Result<()> {
312        let output = self.output.as_mut().expect("output not yet closed");
313
314        for entry in entries {
315            // Transient exclusion rule: skip transient entries when no filters are active
316            if !any_filter_active && entry.transient {
317                continue;
318            }
319
320            // Apply filters
321            if let Some(f) = input_filter {
322                if !f.matches(&entry.tag) {
323                    continue;
324                }
325            }
326            if let Some(ref f) = self.output_filter {
327                if !f.matches(&entry.tag) {
328                    continue;
329                }
330            }
331
332            output.write_all(entry.text.as_bytes())?;
333        }
334
335        Ok(())
336    }
337
338    /// Core input implementation — shared by `.input()` and `.input_filtered()`.
339    fn input_impl(&mut self, path: &Path, input_filter: Option<&Pattern>) -> io::Result<&mut Self> {
340        let is_stdin = path == Path::new("-");
341
342        if is_stdin {
343            return self.stdin_impl_with_filter(input_filter);
344        }
345
346        let canonical = match normalize_path(path) {
347            Ok(p) => p,
348            Err(e) if e.kind() == io::ErrorKind::NotFound => {
349                eprintln!(
350                    "docextract: warning: input file not found: {}",
351                    path.display()
352                );
353                return Ok(self);
354            }
355            Err(e) => return Err(e),
356        };
357
358        CACHE.with(|c| {
359            let mut cache = c.borrow_mut();
360
361            // Check cache first
362            if let Some(range) = cache.ranges.get(&canonical).cloned() {
363                let any_filter_active = self.output_filter.is_some() || input_filter.is_some();
364                self.emit_entries(&cache.entries[range], input_filter, any_filter_active)?;
365                return Ok(self);
366            }
367
368            // Cache miss — read file, parse, store
369            let file = match std::fs::File::open(path) {
370                Ok(f) => f,
371                Err(e) if e.kind() == io::ErrorKind::NotFound => {
372                    eprintln!(
373                        "docextract: warning: input file not found: {}",
374                        path.display()
375                    );
376                    return Ok(self);
377                }
378                Err(e) => return Err(e),
379            };
380
381            let content = {
382                let mut buf = String::new();
383                let mut reader = std::io::BufReader::new(file);
384                reader.read_to_string(&mut buf)?;
385                buf
386            };
387
388            if self.rerun_if_changed {
389                println!("cargo:rerun-if-changed={}", path.display());
390            }
391
392            let initial_tag = path_stem(path);
393            let new_entries = parse_doc_entries(&mut cache.tags, &content, &initial_tag);
394            let start = cache.entries.len();
395            cache.entries.extend(new_entries);
396            let end = cache.entries.len();
397            cache.ranges.insert(canonical, start..end);
398
399            let any_filter_active = self.output_filter.is_some() || input_filter.is_some();
400            self.emit_entries(&cache.entries[start..end], input_filter, any_filter_active)?;
401
402            Ok(self)
403        })
404    }
405
406    fn stdin_impl(&mut self) -> io::Result<&mut Self> {
407        self.stdin_impl_with_filter(None)
408    }
409
410    fn stdin_impl_with_filter(&mut self, input_filter: Option<&Pattern>) -> io::Result<&mut Self> {
411        let key = PathBuf::from("-");
412
413        CACHE.with(|c| {
414            let mut cache = c.borrow_mut();
415
416            // Check cache first
417            if let Some(range) = cache.ranges.get(&key).cloned() {
418                let any_filter_active = self.output_filter.is_some() || input_filter.is_some();
419                self.emit_entries(&cache.entries[range], input_filter, any_filter_active)?;
420                return Ok(self);
421            }
422
423            // Read all of stdin
424            let mut content = String::new();
425            io::stdin().read_to_string(&mut content)?;
426
427            let new_entries = parse_doc_entries(&mut cache.tags, &content, "-");
428            let start = cache.entries.len();
429            cache.entries.extend(new_entries);
430            let end = cache.entries.len();
431            cache.ranges.insert(key, start..end);
432
433            let any_filter_active = self.output_filter.is_some() || input_filter.is_some();
434            self.emit_entries(&cache.entries[start..end], input_filter, any_filter_active)?;
435
436            Ok(self)
437        })
438    }
439
440    /// Flush and close the output writer. Idempotent — safe to call multiple
441    /// times (subsequent calls are no-ops).
442    fn close_output(&mut self) -> io::Result<()> {
443        match self.output.take() {
444            Some(mut writer) => {
445                let result = writer.flush();
446                drop(writer);
447                if let Err(ref e) = result {
448                    eprintln!("docextract: error: output: {e}");
449                }
450                result
451            }
452            None => Ok(()),
453        }
454    }
455}
456
457impl Drop for Docextract {
458    /// Flushes and closes the output writer via `close_output()`.
459    ///
460    /// Flush errors are printed to stderr inside `close_output()` — they
461    /// cannot be returned from `Drop`. After `.done()` has run, the writer
462    /// is `None` and this `close_output()` is a no-op.
463    fn drop(&mut self) {
464        let _ = self.close_output();
465    }
466}
467
468/// Parse all documentation entries from raw file content.
469///
470/// Uses the global tag interning pool for tag deduplication — tags
471/// from all files share one pool.
472#[allow(clippy::too_many_lines)]
473fn parse_doc_entries(
474    pool: &mut HashSet<Rc<str>>,
475    content: &str,
476    initial_tag: &str,
477) -> Vec<DocEntry> {
478    let mut entries = Vec::new();
479
480    let initial_tag_rc = intern_tag(pool, initial_tag);
481    let mut current_tag = Rc::clone(&initial_tag_rc);
482    let mut capture_zone_indent: Option<usize> = None;
483
484    for line_slice in content.split_inclusive('\n') {
485        // Step 1: Try to skip leading whitespace and match four slashes
486        let after_prefix = try_skip_leading_ws_and_four_slashes(line_slice);
487        let Some(after) = after_prefix else {
488            // Check for code-capturing line (non-//// path)
489            let line_content = strip_trailing_newline(line_slice);
490            if let Some((captured_code, template)) = try_split_code_capturing(line_content) {
491                if let Some((tag_name, remaining, is_transient)) = parse_template_tag(template) {
492                    let tag_rc = intern_tag(pool, tag_name);
493                    if is_transient {
494                        let resolved = resolve_placeholders(remaining, captured_code);
495                        let ending = extract_line_ending(line_slice);
496                        let text = format!("{resolved}{ending}");
497                        entries.push(DocEntry {
498                            tag: tag_rc,
499                            text: Box::from(text),
500                            transient: true,
501                        });
502                    } else {
503                        current_tag = tag_rc; // persistent switch, no entry
504                    }
505                } else {
506                    let resolved = resolve_placeholders(template, captured_code);
507                    let ending = extract_line_ending(line_slice);
508                    let text = format!("{resolved}{ending}");
509                    entries.push(DocEntry {
510                        tag: Rc::clone(&current_tag),
511                        text: Box::from(text),
512                        transient: false,
513                    });
514                }
515                // Record indent of this code-capturing line for zone tracking
516                let indent = line_slice
517                    .bytes()
518                    .take_while(|&b| b == b' ' || b == b'\t')
519                    .count();
520                capture_zone_indent = Some(indent);
521            } else {
522                capture_zone_indent = None;
523            }
524            continue;
525        };
526
527        let rest = &line_slice[after..];
528
529        // Step 2: Five+ slashes → ignore
530        if rest.as_bytes().first() == Some(&b'/') {
531            capture_zone_indent = None;
532            continue;
533        }
534
535        // Step 2a: Capture zone continuation — when a //// line
536        // appears at deeper indent than the previous code-capturing
537        // line, treat it as a code-capturing suffix (not a doc line).
538        if let Some(zone_indent) = capture_zone_indent {
539            let line_indent = after - 4; // indent = pos where //// starts
540            if line_indent > zone_indent {
541                // Deeper indent — treat this as code-capturing suffix.
542                // Captured code is just leading whitespace → empty.
543                let template = match rest.as_bytes().first() {
544                    Some(&b' ' | &b'\t') => strip_trailing_newline(&rest[1..]),
545                    Some(&b'\n' | &b'\r') | None => "",
546                    _ => strip_trailing_newline(rest),
547                };
548                if let Some((tag_name, remaining, is_transient)) = parse_template_tag(template) {
549                    let tag_rc = intern_tag(pool, tag_name);
550                    if is_transient {
551                        let resolved = resolve_placeholders(remaining, "");
552                        let ending = extract_line_ending(line_slice);
553                        let text = format!("{resolved}{ending}");
554                        entries.push(DocEntry {
555                            tag: tag_rc,
556                            text: Box::from(text),
557                            transient: true,
558                        });
559                    } else {
560                        current_tag = tag_rc; // persistent switch, no entry
561                    }
562                } else {
563                    let resolved = resolve_placeholders(template, "");
564                    let ending = extract_line_ending(line_slice);
565                    let text = format!("{resolved}{ending}");
566                    entries.push(DocEntry {
567                        tag: Rc::clone(&current_tag),
568                        text: Box::from(text),
569                        transient: false,
570                    });
571                }
572                continue; // keep zone open — do NOT reset indent
573            }
574            capture_zone_indent = None; // not deeper — reset zone
575        }
576
577        // Step 3: Classify by byte after ////
578        let Some(first_byte) = rest.as_bytes().first().copied() else {
579            // "////" at EOF — handle as CASE A (empty text)
580            // This matches P07/P37: empty doc line at EOF → empty-text entry
581            entries.push(DocEntry {
582                tag: Rc::clone(&current_tag),
583                text: Box::from(""),
584                transient: false,
585            });
586            continue;
587        };
588
589        match first_byte {
590            b' ' | b'\t' => {
591                // CASE B: separator → regular doc line
592                let text = &rest[1..]; // strip separator, preserve \n/\r\n
593                entries.push(DocEntry {
594                    tag: Rc::clone(&current_tag),
595                    text: Box::from(text),
596                    transient: false,
597                });
598            }
599            b'\n' | b'\r' => {
600                // CASE C/D: newline after //// → regular doc line (verbatim blank)
601                entries.push(DocEntry {
602                    tag: Rc::clone(&current_tag),
603                    text: Box::from(rest),
604                    transient: false,
605                });
606            }
607            _ => {
608                // Tag directive — parse name and optional text
609                let (name, text_opt) = parse_tag_directive_from_rest(rest);
610
611                // Intern the tag name
612                let tag_rc = intern_tag(pool, name);
613
614                match text_opt {
615                    None => {
616                        // Persistent tag switch — update current_tag, no DocEntry
617                        current_tag = tag_rc;
618                    }
619                    Some(text) => {
620                        // Transient tag — create DocEntry, don't change current_tag
621                        entries.push(DocEntry {
622                            tag: tag_rc,
623                            text: Box::from(text),
624                            transient: true,
625                        });
626                    }
627                }
628            }
629        }
630    }
631
632    entries
633}
634
635/// Try to skip leading ASCII whitespace and match exactly four slashes.
636/// Returns the position after the four slashes, or `None` if not a match.
637fn try_skip_leading_ws_and_four_slashes(line: &str) -> Option<usize> {
638    let b = line.as_bytes();
639    let mut pos: usize = 0;
640
641    // Skip leading ASCII whitespace (space 0x20, tab 0x09)
642    while pos < b.len() && (b[pos] == 0x20 || b[pos] == 0x09) {
643        pos += 1;
644    }
645
646    // Require exactly four slashes (0x2F)
647    if pos + 4 > b.len() {
648        return None;
649    }
650    if b[pos] != 0x2F || b[pos + 1] != 0x2F || b[pos + 2] != 0x2F || b[pos + 3] != 0x2F {
651        return None;
652    }
653
654    Some(pos + 4)
655}
656
657/// Parse a tag directive from a code-capturing template.
658///
659/// Returns `None` if the template starts with `{` (placeholder), `/` (five+
660/// slashes), whitespace, or is empty. Otherwise scans for a space, tab, or
661/// end-of-line to extract the tag name.
662///
663/// Returns `Some((tag_name, remaining_template, is_transient))` where
664/// `is_transient` is `true` when a space or tab was found after the tag name
665/// (indicating inline text follows).
666fn parse_template_tag(template: &str) -> Option<(&str, &str, bool)> {
667    let b = template.as_bytes();
668    if b.is_empty() {
669        return None;
670    }
671    match b[0] {
672        b'{' | b'/' | b' ' | b'\t' => return None,
673        _ => {}
674    }
675    // Scan for space, tab, or EOL to find the tag name boundary.
676    for (i, &byte) in b.iter().enumerate().skip(1) {
677        match byte {
678            b' ' | b'\t' => {
679                return Some((&template[..i], &template[i + 1..], true));
680            }
681            b'\n' | b'\r' => {
682                return Some((&template[..i], &template[i..], false));
683            }
684            _ => {}
685        }
686    }
687    // No space/tab/newline found — persistent switch with empty remaining.
688    Some((template, "", false))
689}
690
691/// Parse a tag directive from the bytes after `////`.
692///
693/// Given `rest` = the bytes after `////` (known to start with a non-whitespace,
694/// non-slash, non-newline byte), returns `(tag_name, optional_text)`.
695fn parse_tag_directive_from_rest(rest: &str) -> (&str, Option<&str>) {
696    // Strip trailing \n or \r\n to get the content without line ending
697    let raw_tag = rest.trim_end_matches(['\n', '\r']);
698
699    // Find first whitespace in raw_tag
700    if let Some(ws_pos) = raw_tag.find(&[' ', '\t'] as &[char]) {
701        let name = &raw_tag[..ws_pos];
702        // text = everything after the whitespace in `rest` (preserving \n)
703        let text = &rest[ws_pos + 1..];
704        (name, Some(text))
705    } else {
706        (raw_tag, None)
707    }
708}
709
710// ---------------------------------------------------------------------
711// Code-lifting: placeholder-based code capture (specs/code-lifting-spec.md)
712//
713// Batch 1 (implemented): Leaf functions — trim helpers, try_split_code_capturing,
714// resolve_placeholders, resolve_single_placeholder, unescape_delimiter,
715// parse_sed_placeholder. Unit tests S01-S18, R01-R21, U01-U05 pass.
716//
717// Batch 2 (integration): Wiring into parse_doc_entries, integration tests
718// (E01-E17, EX01-EX08, F01-F05), and D01-D11 tests for parse_sed_placeholder.
719// `#[allow(dead_code)]` is required because integration wiring hasn't landed
720// yet (or for cfg-gated sed-like paths).
721// ---------------------------------------------------------------------
722
723/// Return the length after stripping trailing ASCII space (0x20) and tab (0x09).
724///
725/// Contract: code-lifting-spec.md §6.4 (REQ-LIFT-F-003). Returns the byte
726/// index of the first trailing space/tab byte — the caller slices `&bytes[..n]`
727/// to get the trimmed content.
728#[allow(
729    dead_code,
730    reason = "only used by tests and code-capturing integration (not yet wired into parse_doc_entries)"
731)]
732fn trim_trailing_space_tab(bytes: &[u8]) -> usize {
733    let mut end = bytes.len();
734    while end > 0 && (bytes[end - 1] == b' ' || bytes[end - 1] == b'\t') {
735        end -= 1;
736    }
737    end
738}
739
740/// Strip leading ASCII space (0x20) and tab (0x09) from `s`.
741///
742/// Contract: code-lifting-spec.md §6.3.2 (REQ-LIFT-F-004).
743/// Used only by `{{}}` resolution.
744#[allow(
745    dead_code,
746    reason = "only used by tests and code-capturing integration"
747)]
748fn trim_leading_space_tab(s: &str) -> &str {
749    let bytes = s.as_bytes();
750    let mut start = 0;
751    while start < bytes.len() && (bytes[start] == b' ' || bytes[start] == b'\t') {
752        start += 1;
753    }
754    &s[start..]
755}
756
757/// Detect a code-capturing line and split it at the rightmost `////`
758/// immediately preceded by space (0x20) or tab (0x09).
759///
760/// Contract: code-lifting-spec.md §6.1.2 (REQ-LIFT-F-001, REQ-LIFT-F-002,
761/// REQ-LIFT-F-003). Returns `Some((captured_code, template))` where captured
762/// code has trailing space/tab stripped. Returns `None` when the line has
763/// no `////` preceded by space/tab.
764///
765/// `line` is the content without trailing `\n` or `\r\n`.
766#[allow(
767    dead_code,
768    reason = "only used by tests and code-capturing integration"
769)]
770fn try_split_code_capturing(line: &str) -> Option<(&str, &str)> {
771    let b = line.as_bytes();
772
773    for i in (0..=b.len().saturating_sub(4)).rev() {
774        // Guard against lines shorter than 4 bytes.
775        if i + 3 >= b.len() {
776            continue;
777        }
778        if b[i] == b'/' && b[i + 1] == b'/' && b[i + 2] == b'/' && b[i + 3] == b'/' {
779            // Require separator (space or tab) before ////
780            if i == 0 || (b[i - 1] != b' ' && b[i - 1] != b'\t') {
781                continue;
782            }
783
784            let separator_pos = i - 1;
785            let after_slashes = i + 4;
786
787            // Captured code: trim trailing space/tab.
788            let code_end = trim_trailing_space_tab(&b[..separator_pos]);
789            let captured_code = &line[..code_end];
790
791            // Doc template: consume one separator byte after //// if present.
792            let template = if after_slashes >= b.len() {
793                ""
794            } else if b[after_slashes] == b' ' || b[after_slashes] == b'\t' {
795                &line[after_slashes + 1..]
796            } else {
797                &line[after_slashes..]
798            };
799
800            return Some((captured_code, template));
801        }
802    }
803
804    None
805}
806
807/// Replace `\<delim>` sequences with a literal `delim` byte.
808///
809/// Contract: code-lifting-spec.md §6.3.4.1 (REQ-LIFT-F-008). Only a backslash
810/// immediately followed by the delimiter byte is unescaped; all other
811/// backslash sequences pass through unchanged.
812///
813/// Iterates at the char level to preserve multi-byte UTF-8 sequences.
814fn unescape_delimiter(s: &str, delim: u8) -> String {
815    let delim_char = delim as char;
816    let mut result = String::with_capacity(s.len());
817    let mut iter = s.chars().peekable();
818    while let Some(ch) = iter.next() {
819        if ch == '\\' {
820            if let Some(&next_ch) = iter.peek() {
821                if next_ch == delim_char {
822                    result.push(delim_char);
823                    iter.next(); // consume the delimiter
824                    continue;
825                }
826            }
827        }
828        result.push(ch);
829    }
830    result
831}
832
833/// Minimal RED scaffolding for the sed-like placeholder parse result.
834///
835/// Contract per code-lifting-spec.md §6.3.4 (REQ-LIFT-F-008): extract mode
836/// (`{{XregexX}}`) has `subst = None`; replace mode (`{{XregexXsubstX}}`)
837/// has `subst = Some(...)`. Struct form is RED scaffolding only — batch 2
838/// (D01–D11 tests) will pin the exact shape when they land.
839#[allow(dead_code, reason = "RED scaffolding; constructed in batch 2")]
840struct SedForm {
841    regex: String,
842    subst: Option<String>,
843}
844
845/// Minimal RED scaffolding for sed-like parse errors.
846#[allow(dead_code, reason = "RED scaffolding; constructed in batch 2")]
847struct SedError(String);
848
849/// Parse a sed-like placeholder form `XregexX` or `XregexXsubstX`.
850///
851/// Contract: code-lifting-spec.md §6.3.4.1 (REQ-LIFT-F-008). `content` is the
852/// text between `{{` and `}}`; the first byte is the delimiter. Returns
853/// extract mode when only two delimiters are found, replace mode when three
854/// are found. Returns `Err(SedError)` when no closing delimiter is found.
855#[allow(
856    dead_code,
857    reason = "only called from cfg(feature = \"regex\") code path"
858)]
859fn parse_sed_placeholder(content: &str) -> Result<SedForm, SedError> {
860    let delim = content.as_bytes()[0];
861    let inner = &content[1..];
862
863    // Find first unescaped delimiter → regex/subst boundary.
864    let mut regex_end: Option<usize> = None;
865    let mut i = 0;
866    while i < inner.len() {
867        if inner.as_bytes()[i] == delim {
868            // Escaped delimiter? Check for preceding backslash.
869            if i > 0 && inner.as_bytes()[i - 1] == b'\\' {
870                i += 1;
871                continue;
872            }
873            regex_end = Some(i);
874            break;
875        }
876        i += 1;
877    }
878
879    let Some(regex_end) = regex_end else {
880        return Err(SedError("unterminated regex".to_string()));
881    };
882
883    let regex_raw = &inner[..regex_end];
884    let after_regex = &inner[regex_end + 1..];
885
886    // Unescape the regex field.
887    let regex_unescaped = unescape_delimiter(regex_raw, delim);
888
889    // Scan for third delimiter (substitution separator) or closing }}.
890    let mut subst_end: Option<usize> = None;
891    let mut j = 0;
892    while j < after_regex.len() {
893        if after_regex.as_bytes()[j] == delim {
894            if j > 0 && after_regex.as_bytes()[j - 1] == b'\\' {
895                j += 1;
896                continue;
897            }
898            subst_end = Some(j);
899            break;
900        }
901        j += 1;
902    }
903
904    match subst_end {
905        Some(end) => {
906            // Replace mode: three delimiters found.
907            let subst_raw = &after_regex[..end];
908            let subst_unescaped = unescape_delimiter(subst_raw, delim);
909            Ok(SedForm {
910                regex: regex_unescaped,
911                subst: Some(subst_unescaped),
912            })
913        }
914        None => {
915            // Extract mode: only two delimiters found.
916            Ok(SedForm {
917                regex: regex_unescaped,
918                subst: None,
919            })
920        }
921    }
922}
923
924/// Check whether a byte is an ASCII punctuation character usable as a
925/// sed-like placeholder delimiter.
926///
927/// Excludes `(`, `)`, `{`, `}` to avoid ambiguity with placeholder braces
928/// and regex group syntax.
929#[allow(
930    dead_code,
931    reason = "only used by resolve_single_placeholder (itself guarded by dead_code)"
932)]
933fn is_ascii_punctuation(b: u8) -> bool {
934    matches!(
935        b,
936        b'!' | b'"'
937            | b'#'
938            | b'$'
939            | b'%'
940            | b'&'
941            | b'\''
942            | b'*'
943            | b'+'
944            | b','
945            | b'-'
946            | b'.'
947            | b'/'
948            | b':'
949            | b';'
950            | b'<'
951            | b'='
952            | b'>'
953            | b'?'
954            | b'@'
955            | b'['
956            | b'\\'
957            | b']'
958            | b'^'
959            | b'_'
960            | b'`'
961            | b'|'
962            | b'~'
963    )
964}
965
966/// Resolve a single `{{...}}` placeholder against captured code.
967///
968/// First-byte dispatch per code-lifting-spec.md §6.3: empty content →
969/// `{{}}` double-trim; digit → `{{N}}` character removal; ASCII punctuation
970/// → sed-like form; anything else → reserved-form panic.
971#[allow(
972    dead_code,
973    reason = "only used by tests and resolve_placeholders (not yet wired into parse_doc_entries)"
974)]
975fn resolve_single_placeholder(content: &str, captured_code: &str) -> String {
976    // {{}} — content is empty because the scanner found "}}" immediately
977    // after "{{". Apply double-trim: trailing already stripped by split,
978    // now strip leading space/tab.
979    if content.is_empty() {
980        return trim_leading_space_tab(captured_code).to_string();
981    }
982
983    let first_byte = content.as_bytes()[0];
984
985    // {{N}} — first byte is '0'..='9'.
986    if first_byte.is_ascii_digit() {
987        let n: usize = content.parse().unwrap_or(usize::MAX);
988        let char_count = captured_code.chars().count();
989        if n >= char_count {
990            return String::new();
991        }
992        return captured_code.chars().skip(n).collect();
993    }
994
995    // Sed-like form — first byte is ASCII punctuation.
996    if is_ascii_punctuation(first_byte) {
997        #[cfg(feature = "regex")]
998        {
999            let form = parse_sed_placeholder(content)
1000                .unwrap_or_else(|e| panic!("docextract: invalid sed placeholder: {}", e.0));
1001
1002            return match form.subst {
1003                None => {
1004                    // Extract mode
1005                    let re = regex_lite::Regex::new(&form.regex).unwrap_or_else(|e| {
1006                        eprintln!("docextract: warning: invalid regex '{}': {}", form.regex, e);
1007                        regex_lite::Regex::new("\\b\\B").expect("\\b\\B is a valid regex pattern")
1008                    });
1009                    match re.find(captured_code) {
1010                        Some(m) => m.as_str().to_string(),
1011                        None => String::new(),
1012                    }
1013                }
1014                Some(subst) => {
1015                    // Replace mode — output only the expanded substitution
1016                    // of the first match; discard non-matched text.
1017                    let re = regex_lite::Regex::new(&form.regex).unwrap_or_else(|e| {
1018                        eprintln!("docextract: warning: invalid regex '{}': {}", form.regex, e);
1019                        regex_lite::Regex::new("\\b\\B").expect("\\b\\B is a valid regex pattern")
1020                    });
1021                    if let Some(m) = re.find(captured_code) {
1022                        re.replace(m.as_str(), subst.as_str()).into_owned()
1023                    } else {
1024                        String::new()
1025                    }
1026                }
1027            };
1028        }
1029        #[cfg(not(feature = "regex"))]
1030        {
1031            panic!(
1032                "docextract: sed-like placeholder '{{{{{content}}}}}' requires the `regex` feature.\n\
1033                 Rebuild with default features (cargo build) or use only {{{{}}}} and {{{{N}}}} placeholders."
1034            );
1035        }
1036    }
1037
1038    // Reserved form — anything else.
1039    panic!(
1040        "docextract: reserved placeholder form '{{{{{content}}}}}'.\n\
1041         Use {{{{}}}}, {{{{N}}}}, or a sed-like form {{{{X...X}}}}."
1042    );
1043}
1044
1045/// Resolve all `{{...}}` placeholders in a template against captured code.
1046///
1047/// Scanner per code-lifting-spec.md §6.5. Unterminated `{{` (no closing `}}`)
1048/// is emitted literally.
1049///
1050/// `captured_code` must already have trailing space/tab stripped.
1051#[allow(
1052    dead_code,
1053    reason = "only used by tests and code-capturing integration"
1054)]
1055fn resolve_placeholders(template: &str, captured_code: &str) -> String {
1056    let mut result = String::new();
1057    let mut pos = 0;
1058
1059    while pos < template.len() {
1060        if template[pos..].starts_with("{{") {
1061            let search_from = pos + 2;
1062            if let Some(close_offset) = template[search_from..].find("}}") {
1063                let close_pos = search_from + close_offset;
1064                let content = &template[search_from..close_pos];
1065                let replacement = resolve_single_placeholder(content, captured_code);
1066                result.push_str(&replacement);
1067                pos = close_pos + 2;
1068            } else {
1069                // No closing }} — emit {{ literally.
1070                result.push_str("{{");
1071                pos += 2;
1072            }
1073        } else {
1074            let ch = template[pos..]
1075                .chars()
1076                .next()
1077                .expect("pos < template.len() guarantees at least one char");
1078            result.push(ch);
1079            pos += ch.len_utf8();
1080        }
1081    }
1082
1083    result
1084}
1085
1086/// Strip a trailing `\n` or `\r\n` from `s`, returning the content
1087/// without the line ending.
1088///
1089/// At EOF (no trailing newline), returns `s` unchanged.
1090fn strip_trailing_newline(s: &str) -> &str {
1091    if let Some(stripped) = s.strip_suffix("\r\n") {
1092        stripped
1093    } else if let Some(stripped) = s.strip_suffix('\n') {
1094        stripped
1095    } else {
1096        s
1097    }
1098}
1099
1100/// Return the line ending of `s`: `"\r\n"`, `"\n"`, or `""` (EOF).
1101fn extract_line_ending(s: &str) -> &str {
1102    if s.ends_with("\r\n") {
1103        "\r\n"
1104    } else if s.ends_with('\n') {
1105        "\n"
1106    } else {
1107        ""
1108    }
1109}
1110
1111#[cfg(test)]
1112mod tests {
1113    #![allow(clippy::unwrap_used)]
1114
1115    // --- B01-B28: Docextract builder API tests (lib-spec.md §11.2) ---
1116
1117    use super::*;
1118    use std::fmt::Write as FmtWrite;
1119    use std::fs;
1120    use std::path::PathBuf;
1121    use std::sync::{Mutex, MutexGuard};
1122
1123    /// Unique per-test temp directory; removed on drop (also on panic).
1124    struct TempDir(PathBuf);
1125
1126    impl TempDir {
1127        fn new(name: &str) -> TempDir {
1128            let dir = std::env::temp_dir().join(format!(
1129                "docextract-test-{}-pid{}-{:?}",
1130                name,
1131                std::process::id(),
1132                std::thread::current().id(),
1133            ));
1134            fs::create_dir_all(&dir).unwrap();
1135            TempDir(dir)
1136        }
1137
1138        fn file(&self, name: &str) -> PathBuf {
1139            self.0.join(name)
1140        }
1141
1142        fn write(&self, name: &str, content: &str) -> PathBuf {
1143            let path = self.file(name);
1144            fs::write(&path, content).unwrap();
1145            path
1146        }
1147
1148        fn write_bytes(&self, name: &str, content: &[u8]) -> PathBuf {
1149            let path = self.file(name);
1150            fs::write(&path, content).unwrap();
1151            path
1152        }
1153    }
1154
1155    impl Drop for TempDir {
1156        fn drop(&mut self) {
1157            let _ = fs::remove_dir_all(&self.0);
1158        }
1159    }
1160
1161    fn read_str(path: &Path) -> String {
1162        fs::read_to_string(path).unwrap()
1163    }
1164
1165    /// Serializes `OUT_DIR` mutation: env vars are process-global and tests run
1166    /// in parallel, so tests that read `OUT_DIR` must not race each other.
1167    static OUT_DIR_LOCK: Mutex<()> = Mutex::new(());
1168
1169    /// RAII guard: sets/removes `OUT_DIR` for the duration of the guard and
1170    /// restores the previous value on drop.
1171    struct OutDirGuard {
1172        prev: Option<std::ffi::OsString>,
1173        _lock: MutexGuard<'static, ()>,
1174    }
1175
1176    impl OutDirGuard {
1177        fn with(value: Option<&std::ffi::OsStr>) -> OutDirGuard {
1178            let lock = OUT_DIR_LOCK.lock().unwrap();
1179            let prev = std::env::var_os("OUT_DIR");
1180            match value {
1181                Some(v) => unsafe { std::env::set_var("OUT_DIR", v) },
1182                None => unsafe { std::env::remove_var("OUT_DIR") },
1183            }
1184            OutDirGuard { prev, _lock: lock }
1185        }
1186    }
1187
1188    impl Drop for OutDirGuard {
1189        fn drop(&mut self) {
1190            match &self.prev {
1191                Some(v) => unsafe { std::env::set_var("OUT_DIR", v) },
1192                None => unsafe { std::env::remove_var("OUT_DIR") },
1193            }
1194        }
1195    }
1196
1197    #[test]
1198    fn b01_single_file_extraction() {
1199        // BUILDER-F-001: `.input("valid.rs")` → output file contains extracted docs.
1200        // No interspersed non-doc code means no block break → no auto-separator.
1201        // (The tag-filter model removes auto inter-block separators; entries are
1202        // concatenated back-to-back per tag-filter-spec.md §6.2.4.)
1203        let tmp = TempDir::new("b01");
1204        let src = tmp.write(
1205            "valid.rs",
1206            "//// Hello World\nfn main() {}\n//// Second line\n",
1207        );
1208        let out = tmp.file("out.md");
1209        Docextract::new(&out)
1210            .unwrap()
1211            .input(&src)
1212            .unwrap()
1213            .done()
1214            .unwrap();
1215        // Entries are concatenated without separators in the cache-first model
1216        assert_eq!(read_str(&out), "Hello World\nSecond line\n");
1217    }
1218
1219    #[test]
1220    fn b02_multiple_files_concatenated() {
1221        // BUILDER-F-002: two files → docs concatenated, no inter-file separator (§5.1)
1222        let tmp = TempDir::new("b02");
1223        let a = tmp.write("a.rs", "//// From A\n");
1224        let b = tmp.write("b.rs", "//// From B\n");
1225        let out = tmp.file("out.md");
1226        Docextract::new(&out)
1227            .unwrap()
1228            .input(&a)
1229            .unwrap()
1230            .input(&b)
1231            .unwrap()
1232            .done()
1233            .unwrap();
1234        assert_eq!(read_str(&out), "From A\nFrom B\n");
1235    }
1236
1237    #[test]
1238    fn b03_missing_file_warns_and_continues() {
1239        // BUILDER-F-010: file not found → warning to stderr, returns Ok, continues
1240        let tmp = TempDir::new("b03");
1241        let src = tmp.write("valid.rs", "//// From Valid\n");
1242        let out = tmp.file("out.md");
1243        let mut builder = Docextract::new(&out).unwrap();
1244        // Missing input: Ok returned (warning goes to stderr, not captured here).
1245        assert!(builder.input(tmp.file("missing.rs")).is_ok());
1246        // Processing continues with the remaining input.
1247        builder.input(&src).unwrap();
1248        builder.done().unwrap();
1249        assert_eq!(read_str(&out), "From Valid\n");
1250    }
1251
1252    #[test]
1253    fn b04_zero_inputs_empty_output() {
1254        // BUILDER-F-003: `.done()` with zero inputs → empty output file, Ok
1255        let tmp = TempDir::new("b04");
1256        let out = tmp.file("out.md");
1257        Docextract::new(&out).unwrap().done().unwrap();
1258        assert!(out.exists());
1259        assert_eq!(read_str(&out), "");
1260    }
1261
1262    #[test]
1263    fn b05_stdin_input() {
1264        // BUILDER-F-004: extraction from a stream source.
1265        let tmp = TempDir::new("b05");
1266        let src = tmp.write("stdin-content.txt", "//// From stdin\n");
1267        let out = tmp.file("out.md");
1268        Docextract::new(&out)
1269            .unwrap()
1270            .input(&src)
1271            .unwrap()
1272            .done()
1273            .unwrap();
1274        assert_eq!(read_str(&out), "From stdin\n");
1275    }
1276
1277    #[test]
1278    fn b06_stdin_and_file_combined() {
1279        // BUILDER-F-005: mix `.input("file.rs")` + `.stdin()` → both sources
1280        let tmp = TempDir::new("b06");
1281        let file = tmp.write("file.rs", "//// From File\n");
1282        let stdin_content = tmp.write("stdin.txt", "//// From stdin\n");
1283        let out = tmp.file("out.md");
1284        Docextract::new(&out)
1285            .unwrap()
1286            .input(&file)
1287            .unwrap()
1288            .input(&stdin_content)
1289            .unwrap()
1290            .done()
1291            .unwrap();
1292        assert_eq!(read_str(&out), "From File\nFrom stdin\n");
1293    }
1294
1295    #[test]
1296    fn b07_mixed_valid_and_invalid_inputs() {
1297        // BUILDER-F-001/016: doc-bearing file + file with only non-doc lines
1298        let tmp = TempDir::new("b07");
1299        let docs = tmp.write("docs.rs", "//// Kept\n");
1300        let no_docs = tmp.write(
1301            "code.rs",
1302            "fn main() {\n    // not a doc\n}\n////Bad\n///// five\n////### Heading\n",
1303        );
1304        let out = tmp.file("out.md");
1305        Docextract::new(&out)
1306            .unwrap()
1307            .input(&docs)
1308            .unwrap()
1309            .input(&no_docs)
1310            .unwrap()
1311            .done()
1312            .unwrap();
1313        // Non-doc lines silently ignored; `////Bad` is a tag directive (no entry);
1314        // only `docs.rs` contributes.
1315        assert_eq!(read_str(&out), "Kept\n");
1316    }
1317
1318    #[test]
1319    fn b08_read_error_returns_err() {
1320        // BUILDER-F-011: read error (mid-stream) → Err(io::Error).
1321        let tmp = TempDir::new("b08");
1322        let dir = tmp.file("a_directory");
1323        fs::create_dir_all(&dir).unwrap();
1324        let out = tmp.file("out.md");
1325        assert!(Docextract::new(&out).unwrap().input(&dir).is_err());
1326    }
1327
1328    #[test]
1329    fn b09_output_file_created() {
1330        // BUILDER-F-014-adjacent: new() creates (and truncates) the output file
1331        let tmp = TempDir::new("b09");
1332        let out = tmp.file("out.md");
1333        assert!(!out.exists());
1334        let mut builder = Docextract::new(&out).unwrap();
1335        assert!(out.exists(), "output file must be created by new()");
1336        builder.done().unwrap();
1337        // Truncation: pre-existing content is wiped.
1338        let out2 = tmp.file("pre.md");
1339        fs::write(&out2, "stale content").unwrap();
1340        Docextract::new(&out2).unwrap().done().unwrap();
1341        assert_eq!(read_str(&out2), "");
1342    }
1343
1344    #[test]
1345    fn b10_stdout_output_path() {
1346        // BUILDER-F-022: `new("-")` targets stdout — no file named "-" is created.
1347        let tmp = TempDir::new("b10");
1348        Docextract::new("-")
1349            .unwrap()
1350            .input(tmp.write("in.rs", "//// To stdout\n"))
1351            .unwrap()
1352            .done()
1353            .unwrap();
1354        assert!(
1355            !std::path::Path::new("-").exists(),
1356            "no file named '-' should be created in the working directory"
1357        );
1358    }
1359
1360    #[test]
1361    fn b11_rerun_if_changed_false_suppresses() {
1362        // BUILDER-F-007: `.rerun_if_changed(false)` suppresses cargo: directives.
1363        let tmp = TempDir::new("b11");
1364        let src = tmp.write("in.rs", "//// Doc\n");
1365        let out = tmp.file("out.md");
1366        let mut builder = Docextract::new(&out).unwrap();
1367        builder.rerun_if_changed(false);
1368        builder.input(&src).unwrap();
1369        builder.done().unwrap();
1370        assert_eq!(read_str(&out), "Doc\n");
1371    }
1372
1373    #[test]
1374    fn b12_last_toggle_wins() {
1375        // BUILDER-F-008: repeated toggles — the last call wins.
1376        let tmp = TempDir::new("b12");
1377        let src = tmp.write("in.rs", "//// Doc\n");
1378        let out = tmp.file("out.md");
1379        let mut builder = Docextract::new(&out).unwrap();
1380        builder.rerun_if_changed(true);
1381        builder.rerun_if_changed(false);
1382        builder.rerun_if_changed(true);
1383        builder.input(&src).unwrap();
1384        builder.done().unwrap();
1385        assert_eq!(read_str(&out), "Doc\n");
1386    }
1387
1388    #[test]
1389    fn b13_out_dir_set_auto_detects() {
1390        // BUILDER-F-006: with OUT_DIR set, new() auto-enables rerun-if-changed
1391        let tmp = TempDir::new("b13");
1392        let src = tmp.write("in.rs", "//// Doc\n");
1393        let out = tmp.file("out.md");
1394        let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
1395        let mut builder = Docextract::new(&out).unwrap();
1396        builder.input(&src).unwrap();
1397        builder.done().unwrap();
1398        assert_eq!(read_str(&out), "Doc\n");
1399    }
1400
1401    #[test]
1402    fn b14_out_dir_unset_default_false() {
1403        // BUILDER-F-024: with OUT_DIR unset, rerun_if_changed defaults to false.
1404        let tmp = TempDir::new("b14");
1405        let src = tmp.write("in.rs", "//// Doc\n");
1406        let out = tmp.file("out.md");
1407        let _guard = OutDirGuard::with(None);
1408        let mut builder = Docextract::new(&out).unwrap();
1409        builder.input(&src).unwrap();
1410        builder.done().unwrap();
1411        assert_eq!(read_str(&out), "Doc\n");
1412    }
1413
1414    #[test]
1415    fn b15_done_then_drop_no_double_close() {
1416        // BUILDER-F-009 + §6.1: `.done()` is chainable and idempotent
1417        let tmp = TempDir::new("b15");
1418        let src = tmp.write("in.rs", "//// Doc\n");
1419        let out = tmp.file("out.md");
1420        let mut builder = Docextract::new(&out).unwrap();
1421        builder.input(&src).unwrap();
1422        builder.done().unwrap();
1423        builder.done().unwrap();
1424        assert_eq!(read_str(&out), "Doc\n");
1425    }
1426
1427    #[test]
1428    fn b16_drop_without_done_flushes() {
1429        // BUILDER-F-023: Drop flushes and closes the output via close_output().
1430        let tmp = TempDir::new("b16");
1431        let src = tmp.write("in.rs", "//// Doc\n");
1432        let out = tmp.file("out.md");
1433        {
1434            let mut builder = Docextract::new(&out).unwrap();
1435            builder.input(&src).unwrap();
1436            // No .done() — Drop must flush the writer.
1437        }
1438        assert_eq!(read_str(&out), "Doc\n");
1439    }
1440
1441    #[test]
1442    fn b17_empty_file_no_output() {
1443        // BUILDER-F-015: empty input file → no output, no error
1444        let tmp = TempDir::new("b17");
1445        let src = tmp.write("empty.rs", "");
1446        let out = tmp.file("out.md");
1447        Docextract::new(&out)
1448            .unwrap()
1449            .input(&src)
1450            .unwrap()
1451            .done()
1452            .unwrap();
1453        assert_eq!(read_str(&out), "");
1454    }
1455
1456    #[test]
1457    fn b18_no_doc_lines_empty_output() {
1458        // BUILDER-F-016: file with only non-doc lines → empty output, no error.
1459        // In the cache-first model, `////Bad`, `///// five` are all handled:
1460        // `////Bad` is a persistent tag directive (no entry), `/////` is ignored.
1461        let tmp = TempDir::new("b18");
1462        let src = tmp.write(
1463            "code.rs",
1464            "fn main() {\n    println!(\"hi\");\n}\n// regular\n/// rustdoc\n////Bad\n///// five\n",
1465        );
1466        let out = tmp.file("out.md");
1467        Docextract::new(&out)
1468            .unwrap()
1469            .input(&src)
1470            .unwrap()
1471            .done()
1472            .unwrap();
1473        assert_eq!(read_str(&out), "");
1474    }
1475
1476    #[test]
1477    fn b19_crlf_preserved() {
1478        // BUILDER-F-017: CRLF line endings preserved in output.
1479        // Cache-first model: no auto inter-block separators.
1480        let tmp = TempDir::new("b19");
1481        let src = tmp.write(
1482            "crlf.rs",
1483            "//// First\r\n//// Second\r\nlet x = 1;\r\n//// Third\r\n",
1484        );
1485        let out = tmp.file("out.md");
1486        Docextract::new(&out)
1487            .unwrap()
1488            .input(&src)
1489            .unwrap()
1490            .done()
1491            .unwrap();
1492        assert_eq!(read_str(&out), "First\r\nSecond\r\nThird\r\n");
1493    }
1494
1495    #[test]
1496    fn b20_invalid_utf8_errors() {
1497        // BUILDER-F-013 / task B20: invalid UTF-8 input → error.
1498        let tmp = TempDir::new("b20");
1499        let src = tmp.write_bytes("binary.rs", b"//// \xFF\xFE not utf8\n");
1500        let out = tmp.file("out.md");
1501        let mut builder = Docextract::new(&out).unwrap();
1502        assert!(builder.input(&src).is_err());
1503        builder.done().unwrap();
1504    }
1505
1506    #[test]
1507    fn b21_large_file_processing() {
1508        // BUILDER-F-018: ~1 MiB source with 20k doc lines + interspersed code;
1509        // all doc lines extracted, none lost, code lines never leaked.
1510        // Cache-first model: no auto inter-block separators → 20,000 lines.
1511        let tmp = TempDir::new("b21");
1512        let mut content = String::new();
1513        for i in 0..20_000 {
1514            let _ = write!(content, "//// line {i} {}", "x".repeat(40));
1515            content.push('\n');
1516            if i % 5 == 0 {
1517                content.push_str("fn f() {}\n");
1518            }
1519        }
1520        assert!(content.len() >= 1_000_000, "source should be ~1 MiB");
1521        let src = tmp.write("large.rs", &content);
1522        let out = tmp.file("out.md");
1523        Docextract::new(&out)
1524            .unwrap()
1525            .input(&src)
1526            .unwrap()
1527            .done()
1528            .unwrap();
1529        let output = read_str(&out);
1530        assert!(output.starts_with("line 0 "));
1531        assert!(output.ends_with(&format!("line 19999 {}\n", "x".repeat(40))));
1532        // Cache-first: no auto-separators — 20,000 lines total
1533        assert_eq!(output.lines().count(), 20_000);
1534        // Every non-empty line is a doc line — no "fn f()" code leaked.
1535        assert!(
1536            output
1537                .lines()
1538                .filter(|l| !l.is_empty())
1539                .all(|l| l.starts_with("line "))
1540        );
1541        assert!(output.len() > 800_000, "all 20k doc lines must be present");
1542    }
1543
1544    #[test]
1545    fn b22_multiple_inputs_in_loop() {
1546        // BUILDER-F-002: many `.input()` calls (loop style) → all files processed.
1547        let tmp = TempDir::new("b22");
1548        let out = tmp.file("out.md");
1549        let mut builder = Docextract::new(&out).unwrap();
1550        let mut expected = String::new();
1551        for i in 0..10 {
1552            let src = tmp.write(&format!("m{i}.rs"), &format!("//// File {i}\n"));
1553            builder.input(&src).unwrap();
1554            let _ = writeln!(expected, "File {i}");
1555        }
1556        builder.done().unwrap();
1557        assert_eq!(read_str(&out), expected);
1558    }
1559
1560    #[test]
1561    fn b23_done_ok_on_empty_builder() {
1562        // BUILDER-F-003: `.done()` on a builder with no inputs returns Ok(&mut self)
1563        let tmp = TempDir::new("b23");
1564        let out = tmp.file("out.md");
1565        let mut builder = Docextract::new(&out).unwrap();
1566        let result = builder.done();
1567        assert!(result.is_ok());
1568        assert_eq!(read_str(&out), "");
1569    }
1570
1571    #[test]
1572    fn b24_stdin_called_twice_second_noop() {
1573        // BUILDER-F-021: the second source (non-doc lines only, the file analog of
1574        // an exhausted stream) contributes nothing.
1575        let tmp = TempDir::new("b24");
1576        let first = tmp.write("first.txt", "//// Only once\n");
1577        let second = tmp.write("second.txt", "fn main() {\n    let x = 1;\n}\n");
1578        let out = tmp.file("out.md");
1579        Docextract::new(&out)
1580            .unwrap()
1581            .input(&first)
1582            .unwrap()
1583            .input(&second)
1584            .unwrap()
1585            .done()
1586            .unwrap();
1587        assert_eq!(read_str(&out), "Only once\n");
1588    }
1589
1590    #[test]
1591    fn b25_empty_output_path_errors() {
1592        // CLI "missing output argument" analogue at the library level.
1593        let result = Docextract::new("");
1594        assert!(result.is_err());
1595    }
1596
1597    #[test]
1598    fn b26_file_vs_stdout_output_paths() {
1599        // BUILDER-F-001/022: file path creates a real file; "-" path targets stdout.
1600        let tmp = TempDir::new("b26");
1601        let src = tmp.write("in.rs", "//// Doc\n");
1602        let out = tmp.file("out.md");
1603        {
1604            Docextract::new(&out)
1605                .unwrap()
1606                .input(&src)
1607                .unwrap()
1608                .done()
1609                .unwrap();
1610        }
1611        assert!(out.exists());
1612        assert_eq!(read_str(&out), "Doc\n");
1613        let string_path: String = tmp
1614            .write("str.rs", "//// String Doc\n")
1615            .to_string_lossy()
1616            .into_owned();
1617        let out2 = tmp.file("out2.md");
1618        {
1619            Docextract::new(&out2)
1620                .unwrap()
1621                .input(string_path)
1622                .unwrap()
1623                .done()
1624                .unwrap();
1625        }
1626        assert_eq!(read_str(&out2), "String Doc\n");
1627        {
1628            Docextract::new("-")
1629                .unwrap()
1630                .input(&src)
1631                .unwrap()
1632                .done()
1633                .unwrap();
1634        }
1635        assert!(
1636            !std::path::Path::new("-").exists(),
1637            "stdout target must not create a file named '-' in the working directory"
1638        );
1639    }
1640
1641    #[test]
1642    fn b27_mid_stream_error_preserves_earlier_output() {
1643        // §9.4 non-atomic output: when a later input fails, output written by
1644        // earlier inputs is preserved.
1645        let tmp = TempDir::new("b27");
1646        let good = tmp.write("good.rs", "//// From Good\n");
1647        let bad_dir = tmp.file("bad");
1648        fs::create_dir_all(&bad_dir).unwrap();
1649        let out = tmp.file("out.md");
1650        let mut builder = Docextract::new(&out).unwrap();
1651        builder.input(&good).unwrap();
1652        assert!(builder.input(&bad_dir).is_err());
1653        builder.done().unwrap();
1654        assert_eq!(read_str(&out), "From Good\n");
1655    }
1656
1657    #[test]
1658    fn b28_all_doc_line_types_in_one_file() {
1659        // BUILDER-F-001: every valid doc-line form in one file — space separator,
1660        // tab separator, indented, verbatim blank (////), tab indent, two-space
1661        // content, EOF "////" — with directives and ignored lines between.
1662        // Cache-first model: no auto inter-block separators.
1663        let tmp = TempDir::new("b28");
1664        let src = tmp.write(
1665            "all.rs",
1666            "//// First\n////\n//// Second\nlet x = 1;\n\t//// Tab Sep\n////\tTab Content\n////  Two Spaces\n////Bad\n///// five\n////",
1667        );
1668        let out = tmp.file("out.md");
1669        Docextract::new(&out)
1670            .unwrap()
1671            .input(&src)
1672            .unwrap()
1673            .done()
1674            .unwrap();
1675        // `////Bad` is a tag directive (persistent switch, no entry).
1676        // Entries: First, blank, Second, Tab Sep, Tab Content, Two Spaces, EOF empty
1677        // All concatenated without auto-separators.
1678        assert_eq!(
1679            read_str(&out),
1680            "First\n\nSecond\nTab Sep\nTab Content\n Two Spaces\n"
1681        );
1682    }
1683
1684    #[test]
1685    #[cfg(target_os = "linux")]
1686    fn b29_done_flush_error_returns_err() {
1687        // BUILDER-F-012: `.done()` must surface a flush/write failure as Err(io::Error).
1688        let tmp = TempDir::new("b29");
1689        let src = tmp.write("in.rs", "//// Doc\n");
1690        let mut builder = Docextract::new("/dev/full").unwrap();
1691        builder.input(&src).unwrap();
1692        assert!(builder.done().is_err());
1693    }
1694
1695    #[test]
1696    fn b30_all_inputs_missing_warns_and_creates_empty_output() {
1697        // BUILDER-F-020: all inputs missing → one warning per file to stderr.
1698        let tmp = TempDir::new("b30");
1699        let out = tmp.file("out.md");
1700        let mut builder = Docextract::new(&out).unwrap();
1701        assert!(builder.input(tmp.file("m1.rs")).is_ok());
1702        assert!(builder.input(tmp.file("m2.rs")).is_ok());
1703        builder.done().unwrap();
1704        assert!(out.exists());
1705        assert_eq!(read_str(&out), "");
1706    }
1707
1708    #[test]
1709    fn b31_out_dir_auto_detect_set_and_clear() {
1710        // BUILDER-F-006 + BUILDER-F-024: auto-detection via OUT_DIR.
1711        let tmp = TempDir::new("b31");
1712        let src = tmp.write("in.rs", "//// Doc\n");
1713        let out_set = tmp.file("out-set.md");
1714        {
1715            let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
1716            Docextract::new(&out_set)
1717                .unwrap()
1718                .input(&src)
1719                .unwrap()
1720                .done()
1721                .unwrap();
1722        }
1723        let out_clear = tmp.file("out-clear.md");
1724        {
1725            let _guard = OutDirGuard::with(None);
1726            Docextract::new(&out_clear)
1727                .unwrap()
1728                .input(&src)
1729                .unwrap()
1730                .done()
1731                .unwrap();
1732        }
1733        assert_eq!(read_str(&out_set), "Doc\n");
1734        assert_eq!(read_str(&out_clear), "Doc\n");
1735        assert_eq!(read_str(&out_set), read_str(&out_clear));
1736    }
1737
1738    #[test]
1739    fn b32_non_notfound_open_error_returns_err() {
1740        // BUILDER-F-011 (open-error branch): non-NotFound open errors propagate as Err.
1741        let tmp = TempDir::new("b32");
1742        let out = tmp.file("out.md");
1743        let mut builder = Docextract::new(&out).unwrap();
1744        let nul_path = PathBuf::from("docextract-nul\0path");
1745        assert!(builder.input(nul_path).is_err());
1746        builder.done().unwrap();
1747    }
1748
1749    #[test]
1750    #[cfg(target_os = "linux")]
1751    fn b33_drop_flush_error_reports_to_stderr() {
1752        // §6.1: when `.done()` is never called, Drop's close_output() must flush
1753        // and print a flush failure to stderr.
1754        if std::env::var_os("DOCEXTRACT_SUBPROCESS").is_some() {
1755            // Child: extract a doc line into /dev/full, drop without .done().
1756            let tmp = TempDir::new("b33-child");
1757            let src = tmp.write("in.rs", "//// Doc\n");
1758            let mut builder = Docextract::new("/dev/full").unwrap();
1759            builder.input(&src).unwrap();
1760            // Builder drops here — Drop must flush and print the ENOSPC error.
1761            return;
1762        }
1763        // Parent: run the child and assert the flush error reached stderr.
1764        let exe = std::env::current_exe().unwrap();
1765        let output = std::process::Command::new(&exe)
1766            .env("DOCEXTRACT_SUBPROCESS", "1")
1767            .arg("--exact")
1768            .arg("tests::b33_drop_flush_error_reports_to_stderr")
1769            .arg("--nocapture")
1770            .output()
1771            .unwrap();
1772        assert!(
1773            output.status.success(),
1774            "child test binary must exit 0, got {:?}",
1775            output.status
1776        );
1777        let stderr = String::from_utf8_lossy(&output.stderr);
1778        assert!(
1779            stderr.contains("docextract: error: output:"),
1780            "Drop flush error must be printed to stderr, got: {stderr}"
1781        );
1782    }
1783
1784    // ---------------------------------------------------------------------
1785    // Tag-filter feature tests — specs/tag-filter-spec.md §7 (RED phase).
1786    //
1787    // These tests target the tag-filter API specified in tag-filter-spec.md
1788    // §6 (`DocEntry`, `Docextract::parse_doc_entries`, `Pattern`/
1789    // `PatternError` from `crate::pattern`, `filter_output`,
1790    // `input_filtered`).
1791    // ---------------------------------------------------------------------
1792    mod tag_filter {
1793        use super::*;
1794        use crate::pattern::Pattern;
1795        #[cfg(feature = "regex")]
1796        use crate::pattern::PatternError;
1797        use std::rc::Rc;
1798
1799        /// Assert that `actual` entries match the expected
1800        /// `(tag, text, transient)` triples.
1801        fn assert_entries(actual: &[DocEntry], expected: &[(&str, &str, bool)]) {
1802            assert_eq!(
1803                actual.len(),
1804                expected.len(),
1805                "entry count mismatch: got {} expected {}",
1806                actual.len(),
1807                expected.len()
1808            );
1809            for (entry, (tag, text, transient)) in actual.iter().zip(expected) {
1810                assert_eq!(&*entry.tag, *tag, "tag mismatch");
1811                assert_eq!(&*entry.text, *text, "text mismatch");
1812                assert_eq!(entry.transient, *transient, "transient mismatch");
1813            }
1814        }
1815
1816        /// Assert that the interning pool contains exactly `expected` tag names.
1817        fn assert_tags(tags: &HashSet<Rc<str>>, expected: &[&str]) {
1818            assert_eq!(tags.len(), expected.len(), "interning pool size mismatch");
1819            for &name in expected {
1820                assert!(tags.contains(name), "tag {name:?} missing from pool");
1821            }
1822        }
1823
1824        // --- §7.1 parse_doc_entries tests (P01-P37, tag-filter-spec.md) ---
1825
1826        #[test]
1827        fn p01_simple_doc_line() {
1828            // REQ-TAG-F-001 / P01: `//// Hello\n` → one persistent entry under the initial tag
1829            let mut tags = HashSet::new();
1830            let entries = parse_doc_entries(&mut tags, "//// Hello\n", "lib");
1831            assert_entries(&entries, &[("lib", "Hello\n", false)]);
1832            assert_tags(&tags, &["lib"]);
1833        }
1834
1835        #[test]
1836        fn p02_four_space_indent() {
1837            // REQ-TAG-F-001 / P02: leading ASCII whitespace stripped before prefix match
1838            let mut tags = HashSet::new();
1839            let entries = parse_doc_entries(&mut tags, "    //// Hello\n", "lib");
1840            assert_entries(&entries, &[("lib", "Hello\n", false)]);
1841            assert_tags(&tags, &["lib"]);
1842        }
1843
1844        #[test]
1845        fn p03_tab_indent() {
1846            // REQ-TAG-F-001 / P03: tab indent stripped, prefix matched
1847            let mut tags = HashSet::new();
1848            let entries = parse_doc_entries(&mut tags, "\t//// Hello\n", "lib");
1849            assert_entries(&entries, &[("lib", "Hello\n", false)]);
1850            assert_tags(&tags, &["lib"]);
1851        }
1852
1853        #[test]
1854        fn p04_tab_separator() {
1855            // REQ-TAG-F-001 / P04: tab separator stripped exactly once
1856            let mut tags = HashSet::new();
1857            let entries = parse_doc_entries(&mut tags, "////\tHello\n", "lib");
1858            assert_entries(&entries, &[("lib", "Hello\n", false)]);
1859            assert_tags(&tags, &["lib"]);
1860        }
1861
1862        #[test]
1863        fn p05_empty_doc_line_newline() {
1864            // REQ-TAG-F-001 / P05: `////\n` → verbatim blank line entry
1865            let mut tags = HashSet::new();
1866            let entries = parse_doc_entries(&mut tags, "////\n", "lib");
1867            assert_entries(&entries, &[("lib", "\n", false)]);
1868            assert_tags(&tags, &["lib"]);
1869        }
1870
1871        #[test]
1872        fn p06_empty_doc_line_space_newline() {
1873            // REQ-TAG-F-001 / P06: `//// \n` → separator stripped, blank line entry
1874            let mut tags = HashSet::new();
1875            let entries = parse_doc_entries(&mut tags, "//// \n", "lib");
1876            assert_entries(&entries, &[("lib", "\n", false)]);
1877            assert_tags(&tags, &["lib"]);
1878        }
1879
1880        #[test]
1881        fn p07_empty_doc_line_at_eof() {
1882            // REQ-TAG-F-001 / P07: `////` at EOF (no newline) → empty-text entry
1883            let mut tags = HashSet::new();
1884            let entries = parse_doc_entries(&mut tags, "////", "lib");
1885            assert_entries(&entries, &[("lib", "", false)]);
1886            assert_tags(&tags, &["lib"]);
1887        }
1888
1889        #[test]
1890        fn p08_crlf_preserved() {
1891            // REQ-TAG-F-001 / P08: CRLF ending preserved in entry text
1892            let mut tags = HashSet::new();
1893            let entries = parse_doc_entries(&mut tags, "//// Hello\r\n", "lib");
1894            assert_entries(&entries, &[("lib", "Hello\r\n", false)]);
1895            assert_tags(&tags, &["lib"]);
1896        }
1897
1898        #[test]
1899        fn p09_three_spaces_first_is_separator() {
1900            // REQ-TAG-F-001 / P09: one separator stripped, two spaces preserved
1901            let mut tags = HashSet::new();
1902            let entries = parse_doc_entries(&mut tags, "////   \n", "lib");
1903            assert_entries(&entries, &[("lib", "  \n", false)]);
1904            assert_tags(&tags, &["lib"]);
1905        }
1906
1907        #[test]
1908        fn p10_two_spaces_second_preserved() {
1909            // REQ-TAG-F-001 / P10: one separator stripped, one space preserved
1910            let mut tags = HashSet::new();
1911            let entries = parse_doc_entries(&mut tags, "////  Two Spaces\n", "lib");
1912            assert_entries(&entries, &[("lib", " Two Spaces\n", false)]);
1913            assert_tags(&tags, &["lib"]);
1914        }
1915
1916        #[test]
1917        fn p11_long_doc_line_preserved_verbatim() {
1918            // REQ-TAG-F-001 / P11: long doc line (> 256 chars) preserved verbatim
1919            let content = "x".repeat(300);
1920            let input = format!("//// {content}\n");
1921            let mut tags = HashSet::new();
1922            let entries = parse_doc_entries(&mut tags, &input, "myfile");
1923            assert_entries(&entries, &[("myfile", &format!("{content}\n"), false)]);
1924            assert_tags(&tags, &["myfile"]);
1925        }
1926
1927        #[test]
1928        fn p12_five_slashes_ignored() {
1929            // REQ-TAG-F-001 / P12: five slashes → silently ignored
1930            let mut tags = HashSet::new();
1931            let entries = parse_doc_entries(&mut tags, "/////\n", "lib");
1932            assert_entries(&entries, &[]);
1933            assert_tags(&tags, &["lib"]);
1934        }
1935
1936        #[test]
1937        fn p13_six_slashes_ignored() {
1938            // REQ-TAG-F-001 / P13: six slashes → silently ignored
1939            let mut tags = HashSet::new();
1940            let entries = parse_doc_entries(&mut tags, "//////\n", "lib");
1941            assert_entries(&entries, &[]);
1942            assert_tags(&tags, &["lib"]);
1943        }
1944
1945        #[test]
1946        fn p14_three_slashes_ignored() {
1947            // REQ-TAG-F-001 / P14: `///\n` — fewer than four slashes → ignored
1948            let mut tags = HashSet::new();
1949            let entries = parse_doc_entries(&mut tags, "///\n", "lib");
1950            assert_entries(&entries, &[]);
1951            assert_tags(&tags, &["lib"]);
1952        }
1953
1954        #[test]
1955        fn p15_non_four_slash_prefix_ignored() {
1956            // REQ-TAG-F-001 / P15: first four bytes not all slashes → ignored
1957            let mut tags = HashSet::new();
1958            let entries = parse_doc_entries(&mut tags, "X///\nfn main() {}\n", "lib");
1959            assert_entries(&entries, &[]);
1960            assert_tags(&tags, &["lib"]);
1961        }
1962
1963        #[test]
1964        fn p16_whitespace_only_line_at_eof_ignored() {
1965            // REQ-TAG-F-001 / P16: whitespace-only line at EOF → fewer than
1966            // four bytes remain after whitespace skip → ignored
1967            let mut tags = HashSet::new();
1968            let entries = parse_doc_entries(&mut tags, "    ", "lib");
1969            assert_entries(&entries, &[]);
1970            assert_tags(&tags, &["lib"]);
1971        }
1972
1973        #[test]
1974        fn p17_mixed_indent() {
1975            // REQ-TAG-F-001 / P17: mixed space+tab indent skipped
1976            let mut tags = HashSet::new();
1977            let entries = parse_doc_entries(&mut tags, " \t//// Hello\n", "lib");
1978            assert_entries(&entries, &[("lib", "Hello\n", false)]);
1979            assert_tags(&tags, &["lib"]);
1980        }
1981
1982        #[test]
1983        fn p18_space_separator_at_eof() {
1984            // REQ-TAG-F-001 / P18: `//// ` at EOF → separator stripped, empty text
1985            let mut tags = HashSet::new();
1986            let entries = parse_doc_entries(&mut tags, "//// ", "lib");
1987            assert_entries(&entries, &[("lib", "", false)]);
1988            assert_tags(&tags, &["lib"]);
1989        }
1990
1991        #[test]
1992        fn p19_tab_separator_at_eof() {
1993            // REQ-TAG-F-001 / P19: `////\t` at EOF → separator stripped, empty text
1994            let mut tags = HashSet::new();
1995            let entries = parse_doc_entries(&mut tags, "////\t", "lib");
1996            assert_entries(&entries, &[("lib", "", false)]);
1997            assert_tags(&tags, &["lib"]);
1998        }
1999
2000        #[test]
2001        fn p20_crlf_without_separator() {
2002            // REQ-TAG-F-001 / P20: `////\r\n` → CRLF preserved, no separator to strip
2003            let mut tags = HashSet::new();
2004            let entries = parse_doc_entries(&mut tags, "////\r\n", "lib");
2005            assert_entries(&entries, &[("lib", "\r\n", false)]);
2006            assert_tags(&tags, &["lib"]);
2007        }
2008
2009        #[test]
2010        fn p21_cr_at_eof() {
2011            // REQ-TAG-F-001 / P21: `////\r` (lone CR at EOF) → preserved
2012            let mut tags = HashSet::new();
2013            let entries = parse_doc_entries(&mut tags, "////\r", "lib");
2014            assert_entries(&entries, &[("lib", "\r", false)]);
2015            assert_tags(&tags, &["lib"]);
2016        }
2017
2018        #[test]
2019        fn p22_persistent_tag_switch() {
2020            // REQ-TAG-F-002 / P22: `////foo` is a persistent switch — no
2021            // DocEntry emitted, tag added to pool
2022            let mut tags = HashSet::new();
2023            let entries = parse_doc_entries(&mut tags, "////foo\n", "lib");
2024            assert_entries(&entries, &[]);
2025            assert_tags(&tags, &["lib", "foo"]);
2026        }
2027
2028        #[test]
2029        fn p23_persistent_tag_switch_chapter1() {
2030            // REQ-TAG-F-002 / P23: `////chapter1` → persistent switch
2031            let mut tags = HashSet::new();
2032            let entries = parse_doc_entries(&mut tags, "////chapter1\n", "lib");
2033            assert_entries(&entries, &[]);
2034            assert_tags(&tags, &["lib", "chapter1"]);
2035        }
2036
2037        #[test]
2038        fn p24_transient_tag_with_text() {
2039            // REQ-TAG-F-003 / P24: `////foo bar baz` → transient entry with
2040            // tag `foo`, text `bar baz\n`, transient=true
2041            let mut tags = HashSet::new();
2042            let entries = parse_doc_entries(&mut tags, "////foo bar baz\n", "lib");
2043            assert_entries(&entries, &[("foo", "bar baz\n", true)]);
2044            assert_tags(&tags, &["lib", "foo"]);
2045        }
2046
2047        #[test]
2048        fn p25_transient_tag_glossary() {
2049            // REQ-TAG-F-003 / P25: `////glossary example` → transient entry
2050            let mut tags = HashSet::new();
2051            let entries = parse_doc_entries(&mut tags, "////glossary example\n", "lib");
2052            assert_entries(&entries, &[("glossary", "example\n", true)]);
2053            assert_tags(&tags, &["lib", "glossary"]);
2054        }
2055
2056        #[test]
2057        fn p26_tag_with_hyphen() {
2058            // REQ-TAG-F-002 / P26: hyphen allowed in tag names (§6.1.3)
2059            let mut tags = HashSet::new();
2060            let entries = parse_doc_entries(&mut tags, "////tag-name\n", "lib");
2061            assert_entries(&entries, &[]);
2062            assert_tags(&tags, &["lib", "tag-name"]);
2063        }
2064
2065        #[test]
2066        fn p27_tag_with_dot() {
2067            // REQ-TAG-F-002 / P27: dot allowed in tag names
2068            let mut tags = HashSet::new();
2069            let entries = parse_doc_entries(&mut tags, "////tag.name\n", "lib");
2070            assert_entries(&entries, &[]);
2071            assert_tags(&tags, &["lib", "tag.name"]);
2072        }
2073
2074        #[test]
2075        fn p28_hash_tag() {
2076            // REQ-TAG-F-003 / P28: `////### Heading` → transient tag `###`
2077            let mut tags = HashSet::new();
2078            let entries = parse_doc_entries(&mut tags, "////### Heading\n", "lib");
2079            assert_entries(&entries, &[("###", "Heading\n", true)]);
2080            assert_tags(&tags, &["lib", "###"]);
2081        }
2082
2083        #[test]
2084        fn p29_numeric_tag() {
2085            // REQ-TAG-F-002 / P29: numeric tag names allowed
2086            let mut tags = HashSet::new();
2087            let entries = parse_doc_entries(&mut tags, "////42\n", "lib");
2088            assert_entries(&entries, &[]);
2089            assert_tags(&tags, &["lib", "42"]);
2090        }
2091
2092        #[test]
2093        fn p30_indented_tag_directive() {
2094            // REQ-TAG-F-002 / P30: tag directives may be indented
2095            let mut tags = HashSet::new();
2096            let entries = parse_doc_entries(&mut tags, "    ////foo\n", "lib");
2097            assert_entries(&entries, &[]);
2098            assert_tags(&tags, &["lib", "foo"]);
2099        }
2100
2101        #[test]
2102        fn p31_hello_repurposed_case_e() {
2103            // REQ-TAG-F-002 / P31: `////Hello` (old CASE E) is now a
2104            // persistent tag switch — no DocEntry, no output
2105            let mut tags = HashSet::new();
2106            let entries = parse_doc_entries(&mut tags, "////Hello\n", "lib");
2107            assert_entries(&entries, &[]);
2108            assert_tags(&tags, &["lib", "Hello"]);
2109        }
2110
2111        #[test]
2112        fn p32_persistent_switch_then_doc_line() {
2113            // REQ-TAG-F-002 / P32: doc line after persistent switch uses the
2114            // new tag
2115            let mut tags = HashSet::new();
2116            let entries = parse_doc_entries(&mut tags, "////foo\n//// bar\n", "lib");
2117            assert_entries(&entries, &[("foo", "bar\n", false)]);
2118            assert_tags(&tags, &["lib", "foo"]);
2119        }
2120
2121        #[test]
2122        fn p33_transient_does_not_change_current_tag() {
2123            // REQ-TAG-F-003 / P33: transient entry does NOT change the
2124            // current tag; following doc line keeps the pre-transient tag
2125            let mut tags = HashSet::new();
2126            let entries =
2127                parse_doc_entries(&mut tags, "////foo\n////baz text\n//// after\n", "lib");
2128            assert_entries(
2129                &entries,
2130                &[("baz", "text\n", true), ("foo", "after\n", false)],
2131            );
2132            assert_tags(&tags, &["lib", "foo", "baz"]);
2133        }
2134
2135        #[test]
2136        fn p34_tag_interning_shared_rc() {
2137            // REQ-TAG-F-001 / P34: identical tags share ONE Rc<str>
2138            // allocation via the interning pool (§6.2.1)
2139            let mut tags = HashSet::new();
2140            let entries = parse_doc_entries(&mut tags, "//// a\n//// b\n//// c\n", "mod");
2141            assert_eq!(entries.len(), 3);
2142            assert!(Rc::ptr_eq(&entries[0].tag, &entries[1].tag));
2143            assert!(Rc::ptr_eq(&entries[1].tag, &entries[2].tag));
2144            assert_tags(&tags, &["mod"]);
2145        }
2146
2147        #[test]
2148        fn p35_stdin_initial_tag() {
2149            // REQ-TAG-F-004 / P35: stdin initial tag is the sentinel `-` (§6.3)
2150            let mut tags = HashSet::new();
2151            let entries = parse_doc_entries(&mut tags, "//// hello\n", "-");
2152            assert_entries(&entries, &[("-", "hello\n", false)]);
2153            assert_tags(&tags, &["-"]);
2154        }
2155
2156        #[test]
2157        fn p36_no_doc_lines() {
2158            // REQ-TAG-F-001 / P36: file with no `////` lines → empty entries
2159            let mut tags = HashSet::new();
2160            let entries = parse_doc_entries(&mut tags, "fn main() {\n    let x = 1;\n}\n", "lib");
2161            assert_entries(&entries, &[]);
2162            assert_tags(&tags, &["lib"]);
2163        }
2164
2165        #[test]
2166        fn p37_doc_at_eof_without_newline() {
2167            // REQ-TAG-F-001 / P37: `////` as the last line at EOF (no
2168            // trailing newline) → empty-text entry
2169            let mut tags = HashSet::new();
2170            let entries = parse_doc_entries(&mut tags, "//// text\n////", "lib");
2171            assert_entries(&entries, &[("lib", "text\n", false), ("lib", "", false)]);
2172            assert_tags(&tags, &["lib"]);
2173        }
2174
2175        // --- §7.2 Pattern matcher — hand-rolled backend (G01-G32) ---
2176
2177        #[cfg(not(feature = "regex"))]
2178        mod simple_matcher {
2179            use super::*;
2180
2181            /// Compile `pattern` (infallible on the hand-rolled path) and
2182            /// test it against `target`.
2183            fn m(pattern: &str, target: &str) -> bool {
2184                Pattern::new(pattern).unwrap().matches(target)
2185            }
2186
2187            #[test]
2188            fn g01_star_matches_everything() {
2189                assert!(m(".*", "anything"));
2190            }
2191
2192            #[test]
2193            fn g02_star_matches_empty() {
2194                assert!(m(".*", ""));
2195            }
2196
2197            #[test]
2198            fn g03_literal_exact_match() {
2199                assert!(m("foo", "foo"));
2200            }
2201
2202            #[test]
2203            fn g04_literal_no_match() {
2204                assert!(!m("foo", "bar"));
2205            }
2206
2207            #[test]
2208            fn g05_prefix_then_star() {
2209                assert!(m("foo.*", "foobar"));
2210            }
2211
2212            #[test]
2213            fn g06_prefix_then_star_wrong_target() {
2214                assert!(!m("foo.*", "barfoo"));
2215            }
2216
2217            #[test]
2218            fn g07_star_then_suffix() {
2219                assert!(m(".*foo", "barfoo"));
2220            }
2221
2222            #[test]
2223            fn g08_star_sandwich() {
2224                assert!(m(".*foo.*", "barfoobaz"));
2225            }
2226
2227            #[test]
2228            fn g09_optional_any_single_char() {
2229                assert!(m(".?", "a"));
2230            }
2231
2232            #[test]
2233            fn g10_optional_any_empty() {
2234                assert!(m(".?", ""));
2235            }
2236
2237            #[test]
2238            fn g11_optional_any_two_chars() {
2239                assert!(!m(".?", "ab"));
2240            }
2241
2242            #[test]
2243            fn g12_optional_any_middle_filled() {
2244                assert!(m("f.?o", "foo"));
2245            }
2246
2247            #[test]
2248            fn g13_optional_any_middle_other() {
2249                assert!(m("f.?o", "fao"));
2250            }
2251
2252            #[test]
2253            fn g14_optional_any_middle_omitted() {
2254                assert!(m("f.?o", "fo"));
2255            }
2256
2257            #[test]
2258            fn g15_chapter_optional_digit() {
2259                assert!(m("chapter.?", "chapter1"));
2260            }
2261
2262            #[test]
2263            fn g16_chapter_optional_omitted() {
2264                assert!(m("chapter.?", "chapter"));
2265            }
2266
2267            #[test]
2268            fn g17_character_class_member() {
2269                assert!(m("[abc]", "a"));
2270            }
2271
2272            #[test]
2273            fn g18_character_class_non_member() {
2274                assert!(!m("[abc]", "d"));
2275            }
2276
2277            #[test]
2278            fn g19_character_class_range() {
2279                assert!(m("[a-z]", "m"));
2280            }
2281
2282            #[test]
2283            fn g20_character_class_range_case_sensitive() {
2284                assert!(!m("[a-z]", "M"));
2285            }
2286
2287            #[test]
2288            fn g21_negated_class_matches_outside() {
2289                assert!(m("[^abc]", "d"));
2290            }
2291
2292            #[test]
2293            fn g22_negated_class_rejects_member() {
2294                assert!(!m("[^abc]", "a"));
2295            }
2296
2297            #[test]
2298            fn g23_escaped_dot_matches_dot() {
2299                assert!(m("\\.", "."));
2300            }
2301
2302            #[test]
2303            fn g24_escaped_dot_rejects_other() {
2304                assert!(!m("\\.", "a"));
2305            }
2306
2307            #[test]
2308            fn g25_escaped_backslash_matches_backslash() {
2309                assert!(m("\\\\", "\\"));
2310            }
2311
2312            #[test]
2313            fn g26_empty_pattern_empty_target() {
2314                assert!(m("", ""));
2315            }
2316
2317            #[test]
2318            fn g27_empty_pattern_nonempty_target() {
2319                assert!(!m("", "a"));
2320            }
2321
2322            #[test]
2323            fn g28_multiple_stars() {
2324                assert!(m(".*.*", "abc"));
2325            }
2326
2327            #[test]
2328            fn g29_unclosed_bracket_matches_literal() {
2329                assert!(m("[", "["));
2330            }
2331
2332            #[test]
2333            fn g30_unclosed_range_literal_fallback() {
2334                assert!(!m("[a", "["));
2335            }
2336
2337            #[test]
2338            fn g31_star_then_optional() {
2339                assert!(m(".*.?", "a"));
2340            }
2341
2342            #[test]
2343            fn g32_optional_then_star() {
2344                assert!(m(".?.*", "abc"));
2345            }
2346
2347            #[test]
2348            fn g33_unquantified_class_not_empty() {
2349                assert!(!m("[abc]", ""));
2350            }
2351        }
2352
2353        // --- §7.2a Pattern matcher — regex backend (R01-R21) ---
2354
2355        #[cfg(feature = "regex")]
2356        mod regex_matcher {
2357            use super::*;
2358
2359            /// Compile `pattern` (regex path — valid patterns must compile)
2360            /// and test it against `target`.
2361            fn m(pattern: &str, target: &str) -> bool {
2362                Pattern::new(pattern).unwrap().matches(target)
2363            }
2364
2365            #[test]
2366            fn r01_posix_alpha_matches_letter() {
2367                assert!(m("[[:alpha:]]", "a"));
2368            }
2369
2370            #[test]
2371            fn r02_posix_alpha_rejects_digit() {
2372                assert!(!m("[[:alpha:]]", "9"));
2373            }
2374
2375            #[test]
2376            fn r03_alpha_alnum_star_bar() {
2377                assert!(m("[[:alpha:]][[:alnum:]]*_bar", "a1_bar"));
2378            }
2379
2380            #[test]
2381            fn r04_alpha_alnum_star_bar_long() {
2382                assert!(m("[[:alpha:]][[:alnum:]]*_bar", "a123foo_bar"));
2383            }
2384
2385            #[test]
2386            fn r05_alpha_alnum_star_bar_short() {
2387                assert!(m("[[:alpha:]][[:alnum:]]*_bar", "a_bar"));
2388            }
2389
2390            #[test]
2391            fn r06_alpha_alnum_star_bar_digit_start() {
2392                assert!(!m("[[:alpha:]][[:alnum:]]*_bar", "1_bar"));
2393            }
2394
2395            #[test]
2396            fn r07_alpha_alnum_star_bar_wrong_suffix() {
2397                assert!(!m("[[:alpha:]][[:alnum:]]*_bar", "a_baz"));
2398            }
2399
2400            #[test]
2401            fn r08_group_plus_repeated() {
2402                assert!(m("(foo)+", "foofoofoo"));
2403            }
2404
2405            #[test]
2406            fn r09_group_plus_single() {
2407                assert!(m("(foo)+", "foo"));
2408            }
2409
2410            #[test]
2411            fn r10_group_plus_empty() {
2412                assert!(!m("(foo)+", ""));
2413            }
2414
2415            #[test]
2416            fn r11_alternation_first_branch() {
2417                assert!(m("foo|bar", "foo"));
2418            }
2419
2420            #[test]
2421            fn r12_alternation_second_branch() {
2422                assert!(m("foo|bar", "bar"));
2423            }
2424
2425            #[test]
2426            fn r13_alternation_no_branch() {
2427                assert!(!m("foo|bar", "baz"));
2428            }
2429
2430            #[test]
2431            fn r14_digit_plus() {
2432                assert!(m("\\d+", "123"));
2433            }
2434
2435            #[test]
2436            fn r15_digit_plus_rejects_letters() {
2437                assert!(!m("\\d+", "abc"));
2438            }
2439
2440            #[test]
2441            fn r16_word_plus() {
2442                assert!(m("\\w+", "hello_world"));
2443            }
2444
2445            #[test]
2446            fn r17_exact_count_quantifier() {
2447                assert!(m("a{3}", "aaa"));
2448            }
2449
2450            #[test]
2451            fn r18_exact_count_quantifier_short() {
2452                assert!(!m("a{3}", "aa"));
2453            }
2454
2455            #[test]
2456            fn r19_non_capturing_group() {
2457                assert!(m("(?:foo)", "foo"));
2458            }
2459
2460            #[test]
2461            fn r20_unclosed_bracket_is_compile_error() {
2462                let result = Pattern::new("[");
2463                assert!(
2464                    matches!(result, Err(PatternError::InvalidSyntax(_))),
2465                    "unclosed character class must be a compile error"
2466                );
2467            }
2468
2469            #[test]
2470            fn r21_unclosed_paren_is_compile_error() {
2471                let result = Pattern::new("(");
2472                assert!(
2473                    matches!(result, Err(PatternError::InvalidSyntax(_))),
2474                    "unclosed group must be a compile error"
2475                );
2476            }
2477        }
2478
2479        // --- §7.3 Library API filtering tests (F01-F26) ---
2480
2481        #[test]
2482        fn f01_input_filtered_matches_tag() {
2483            // REQ-TAG-F-005 / F01: `.input_filtered("file.rs", "api")`
2484            // emits only api-tagged lines (transient included — filter active)
2485            let tmp = TempDir::new("f01");
2486            let src = tmp.write("file.rs", "////api intro\n//// core\n////api detail\n");
2487            let out = tmp.file("out.md");
2488            Docextract::new(&out)
2489                .unwrap()
2490                .input_filtered(&src, "api")
2491                .unwrap()
2492                .done()
2493                .unwrap();
2494            assert_eq!(read_str(&out), "intro\ndetail\n");
2495        }
2496
2497        #[test]
2498        fn f02_input_filtered_no_matching_tag() {
2499            // REQ-TAG-F-005 / F02: no api-tagged lines → empty output, no error
2500            let tmp = TempDir::new("f02");
2501            let src = tmp.write("file.rs", "//// core\n");
2502            let out = tmp.file("out.md");
2503            Docextract::new(&out)
2504                .unwrap()
2505                .input_filtered(&src, "api")
2506                .unwrap()
2507                .done()
2508                .unwrap();
2509            assert_eq!(read_str(&out), "");
2510        }
2511
2512        #[test]
2513        fn f03_output_filter_with_unfiltered_input() {
2514            // REQ-TAG-F-006 / F03: `.filter_output(Some("chapter.*"))` +
2515            // `.input()` → only chapter.*-tagged lines
2516            let tmp = TempDir::new("f03");
2517            let src = tmp.write("file.rs", "////chapter1 a\n//// intro\n////chapter2 b\n");
2518            let out = tmp.file("out.md");
2519            Docextract::new(&out)
2520                .unwrap()
2521                .filter_output(Some("chapter.*"))
2522                .unwrap()
2523                .input(&src)
2524                .unwrap()
2525                .done()
2526                .unwrap();
2527            assert_eq!(read_str(&out), "a\nb\n");
2528        }
2529
2530        #[test]
2531        fn f04_output_and_input_filter_and_combine() {
2532            // REQ-TAG-F-006 / F04: output filter chapter.* AND input filter
2533            // chapter1 → only chapter1 lines (§8.7 AND semantics)
2534            let tmp = TempDir::new("f04");
2535            let src = tmp.write("file.rs", "////chapter1 a\n////chapter2 b\n//// plain\n");
2536            let out = tmp.file("out.md");
2537            Docextract::new(&out)
2538                .unwrap()
2539                .filter_output(Some("chapter.*"))
2540                .unwrap()
2541                .input_filtered(&src, "chapter1")
2542                .unwrap()
2543                .done()
2544                .unwrap();
2545            assert_eq!(read_str(&out), "a\n");
2546        }
2547
2548        #[test]
2549        fn f05_reordering_via_multiple_filtered_reads() {
2550            // REQ-TAG-F-007 / F05: ch1, ch1, ch2 reads → ch1 lines then ch2
2551            // lines; the file is read/parsed once (cache — rewrite proves it)
2552            let tmp = TempDir::new("f05");
2553            let src = tmp.write("f.rs", "////ch1 one\n////ch2 two\n////ch1 three\n");
2554            let out = tmp.file("out.md");
2555            let mut builder = Docextract::new(&out).unwrap();
2556            builder.input_filtered(&src, "ch1").unwrap();
2557            // Cache proof: a rewritten file must NOT be re-read on cache hit.
2558            fs::write(&src, "////ch1 REWRITTEN\n").unwrap();
2559            builder.input_filtered(&src, "ch1").unwrap();
2560            builder.input_filtered(&src, "ch2").unwrap();
2561            builder.done().unwrap();
2562            assert_eq!(read_str(&out), "one\nthree\none\nthree\ntwo\n");
2563        }
2564
2565        #[test]
2566        fn f06_filtered_then_unfiltered_rerun() {
2567            // REQ-TAG-F-008 / F06: filtered read then unfiltered `.input()`
2568            // → ch1 lines, then all PERSISTENT lines (cache used on 2nd call;
2569            // transient `ch1` entry skipped in unfiltered mode)
2570            let tmp = TempDir::new("f06");
2571            let src = tmp.write("f.rs", "////ch1 one\n//// plain\n");
2572            let out = tmp.file("out.md");
2573            Docextract::new(&out)
2574                .unwrap()
2575                .input_filtered(&src, "ch1")
2576                .unwrap()
2577                .input(&src)
2578                .unwrap()
2579                .done()
2580                .unwrap();
2581            assert_eq!(read_str(&out), "one\nplain\n");
2582        }
2583
2584        #[test]
2585        fn f07_unfiltered_backward_compat() {
2586            // REQ-TAG-F-010 / F07: `.input()` without filters on a file with
2587            // no tag directives → output identical to the pre-tag-filter
2588            // version
2589            let tmp = TempDir::new("f07");
2590            let src = tmp.write("file.rs", "//// hello\n//// world\n");
2591            let out = tmp.file("out.md");
2592            Docextract::new(&out)
2593                .unwrap()
2594                .input(&src)
2595                .unwrap()
2596                .done()
2597                .unwrap();
2598            assert_eq!(read_str(&out), "hello\nworld\n");
2599        }
2600
2601        #[test]
2602        fn f08_stdin_unfiltered_backward_compat() {
2603            // REQ-TAG-F-010 / F08: stdin parses into cache, emits only
2604            // persistent entries.
2605            let tmp = TempDir::new("f08");
2606            let src = tmp.write("stdin-content.txt", "//// persistent\n////t transient\n");
2607            let out = tmp.file("out.md");
2608            Docextract::new(&out)
2609                .unwrap()
2610                .input(&src)
2611                .unwrap()
2612                .done()
2613                .unwrap();
2614            assert_eq!(read_str(&out), "persistent\n");
2615        }
2616
2617        #[test]
2618        fn f09_rerun_if_changed_emitted_once() {
2619            // REQ-TAG-F-006 / F09: with a cached file, `cargo:rerun-if-changed`
2620            // is emitted only on the FIRST access (cache miss).
2621            if std::env::var_os("DOCEXTRACT_F09_SUBPROCESS").is_some() {
2622                // Child: OUT_DIR set (auto-enables rerun-if-changed), access
2623                // the same file twice → exactly one directive on stdout.
2624                let tmp = TempDir::new("f09-child");
2625                let src = tmp.write("in.rs", "////api doc\n");
2626                let out = tmp.file("out.md");
2627                let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
2628                let mut builder = Docextract::new(&out).unwrap();
2629                builder.input_filtered(&src, "api").unwrap(); // cache miss → directive
2630                builder.input_filtered(&src, "api").unwrap(); // cache hit → no directive
2631                builder.done().unwrap();
2632                return;
2633            }
2634            // Parent: run the child and count directive emissions on stdout.
2635            let exe = std::env::current_exe().unwrap();
2636            let output = std::process::Command::new(&exe)
2637                .env("DOCEXTRACT_F09_SUBPROCESS", "1")
2638                .arg("--exact")
2639                .arg("tests::tag_filter::f09_rerun_if_changed_emitted_once")
2640                .arg("--nocapture")
2641                .output()
2642                .unwrap();
2643            assert!(
2644                output.status.success(),
2645                "child test binary must exit 0, got {:?}",
2646                output.status
2647            );
2648            let stdout = String::from_utf8_lossy(&output.stdout);
2649            let directive_count = stdout.matches("cargo:rerun-if-changed=").count();
2650            assert_eq!(
2651                directive_count, 1,
2652                "rerun-if-changed must be emitted exactly once (first access only), got: {stdout}"
2653            );
2654        }
2655
2656        #[test]
2657        fn f10_persistent_tag_switch_mid_file() {
2658            // REQ-TAG-F-002 / F10: lines before the switch carry the initial
2659            // tag, lines after carry the new tag
2660            let tmp = TempDir::new("f10");
2661            let src = tmp.write("f.rs", "//// first\n////sec\n//// second\n");
2662            let out = tmp.file("out.md");
2663            let mut builder = Docextract::new(&out).unwrap();
2664            builder.input(&src).unwrap(); // unfiltered: both persistent lines
2665            builder.input_filtered(&src, "sec").unwrap(); // proves the 2nd line's tag
2666            builder.done().unwrap();
2667            assert_eq!(read_str(&out), "first\nsecond\nsecond\n");
2668        }
2669
2670        #[test]
2671        fn f11_transient_skipped_when_unfiltered() {
2672            // REQ-TAG-F-003 / F11: transient entry skipped in unfiltered mode
2673            let tmp = TempDir::new("f11");
2674            let src = tmp.write("f.rs", "////t text\n//// regular\n");
2675            let out = tmp.file("out.md");
2676            Docextract::new(&out)
2677                .unwrap()
2678                .input(&src)
2679                .unwrap()
2680                .done()
2681                .unwrap();
2682            assert_eq!(read_str(&out), "regular\n");
2683        }
2684
2685        #[test]
2686        fn f11a_transient_included_when_filter_matches() {
2687            // REQ-TAG-F-003 / F11a: transient entry IS emitted when a filter
2688            // matches its tag
2689            let tmp = TempDir::new("f11a");
2690            let src = tmp.write("f.rs", "////t text\n//// regular\n");
2691            let out = tmp.file("out.md");
2692            Docextract::new(&out)
2693                .unwrap()
2694                .input_filtered(&src, "t")
2695                .unwrap()
2696                .done()
2697                .unwrap();
2698            assert_eq!(read_str(&out), "text\n");
2699        }
2700
2701        #[test]
2702        fn f12_initial_tag_from_filename_stem() {
2703            // REQ-TAG-F-004 / F12: initial tag = filename without extension
2704            let tmp = TempDir::new("f12");
2705            let src = tmp.write("lib.rs", "//// hello\n");
2706            let out = tmp.file("out.md");
2707            Docextract::new(&out)
2708                .unwrap()
2709                .input_filtered(&src, "lib")
2710                .unwrap()
2711                .done()
2712                .unwrap();
2713            assert_eq!(read_str(&out), "hello\n");
2714        }
2715
2716        #[test]
2717        fn f13_nonmatching_filter_empty_output() {
2718            // REQ-TAG-F-005 / F13: filter matching nothing → empty output
2719            let tmp = TempDir::new("f13");
2720            let src = tmp.write("f.rs", "//// hello\n");
2721            let out = tmp.file("out.md");
2722            Docextract::new(&out)
2723                .unwrap()
2724                .input_filtered(&src, "nonexistent")
2725                .unwrap()
2726                .done()
2727                .unwrap();
2728            assert_eq!(read_str(&out), "");
2729        }
2730
2731        #[test]
2732        fn f14_filter_output_none_clears_filter() {
2733            // REQ-TAG-F-006 / F14: `.filter_output(None)` clears the output filter
2734            let tmp = TempDir::new("f14");
2735            let src = tmp.write("f.rs", "////api a\n//// plain\n");
2736            let out = tmp.file("out.md");
2737            let mut builder = Docextract::new(&out).unwrap();
2738            builder.filter_output(Some("api")).unwrap();
2739            builder.input(&src).unwrap();
2740            builder.filter_output(None).unwrap();
2741            builder.input(&src).unwrap();
2742            builder.done().unwrap();
2743            assert_eq!(read_str(&out), "a\nplain\n");
2744        }
2745
2746        #[test]
2747        fn f15_empty_file_with_filter() {
2748            // REQ-TAG-F-005 / F15: empty file + filter → empty output, no error
2749            let tmp = TempDir::new("f15");
2750            let src = tmp.write("empty.rs", "");
2751            let out = tmp.file("out.md");
2752            Docextract::new(&out)
2753                .unwrap()
2754                .input_filtered(&src, "api")
2755                .unwrap()
2756                .done()
2757                .unwrap();
2758            assert_eq!(read_str(&out), "");
2759        }
2760
2761        #[test]
2762        fn f16_only_tag_directives_no_output() {
2763            // REQ-TAG-F-002 / F16: file with only persistent tag switches → empty output
2764            let tmp = TempDir::new("f16");
2765            let src = tmp.write("f.rs", "////api\n////chapter1\n");
2766            let out = tmp.file("out.md");
2767            Docextract::new(&out)
2768                .unwrap()
2769                .input(&src)
2770                .unwrap()
2771                .done()
2772                .unwrap();
2773            assert_eq!(read_str(&out), "");
2774        }
2775
2776        #[test]
2777        fn f17_tag_with_special_chars() {
2778            // REQ-TAG-F-009 / F17: tag `my-tag.v2!` matched by pattern `my-tag.*`
2779            let tmp = TempDir::new("f17");
2780            let src = tmp.write("f.rs", "////my-tag.v2! entry\n//// plain\n");
2781            let out = tmp.file("out.md");
2782            Docextract::new(&out)
2783                .unwrap()
2784                .input_filtered(&src, "my-tag.*")
2785                .unwrap()
2786                .done()
2787                .unwrap();
2788            assert_eq!(read_str(&out), "entry\n");
2789        }
2790
2791        #[test]
2792        fn f18_consecutive_tag_switches_no_output() {
2793            // REQ-TAG-F-002 / F18: consecutive persistent switches with no
2794            // doc lines between them → no output
2795            let tmp = TempDir::new("f18");
2796            let src = tmp.write("f.rs", "////a\n////b\n////c\n");
2797            let out = tmp.file("out.md");
2798            Docextract::new(&out)
2799                .unwrap()
2800                .input(&src)
2801                .unwrap()
2802                .done()
2803                .unwrap();
2804            assert_eq!(read_str(&out), "");
2805        }
2806
2807        #[test]
2808        fn f19_transient_then_transient_current_tag_unchanged() {
2809            // REQ-TAG-F-003 / F19: two consecutive transients each create a
2810            // DocEntry with their own tag; current_tag is unchanged between
2811            // them — the trailing persistent line keeps the initial tag
2812            let tmp = TempDir::new("f19");
2813            let src = tmp.write("f.rs", "////t1 one\n////t2 two\n//// final\n");
2814            let out = tmp.file("out.md");
2815            let mut builder = Docextract::new(&out).unwrap();
2816            builder.input_filtered(&src, "f").unwrap(); // current tag stayed `f`
2817            builder.input_filtered(&src, ".*").unwrap(); // all entries
2818            builder.done().unwrap();
2819            assert_eq!(read_str(&out), "final\none\ntwo\nfinal\n");
2820        }
2821
2822        #[test]
2823        fn f20_no_separator_between_tag_changes() {
2824            // REQ-TAG-F-002 / F20: entries with different tags are emitted
2825            // back-to-back — no blank line is auto-inserted (§8.6)
2826            let tmp = TempDir::new("f20");
2827            let src = tmp.write("f.rs", "////a one\n////b two\n");
2828            let out = tmp.file("out.md");
2829            Docextract::new(&out)
2830                .unwrap()
2831                .input_filtered(&src, ".*")
2832                .unwrap()
2833                .done()
2834                .unwrap();
2835            assert_eq!(read_str(&out), "one\ntwo\n");
2836        }
2837
2838        #[test]
2839        fn f21_explicit_blank_doc_line() {
2840            // REQ-TAG-F-001 / F21: explicit `////` produces a verbatim blank line
2841            let tmp = TempDir::new("f21");
2842            let src = tmp.write("f.rs", "//// one\n////\n//// two\n");
2843            let out = tmp.file("out.md");
2844            Docextract::new(&out)
2845                .unwrap()
2846                .input(&src)
2847                .unwrap()
2848                .done()
2849                .unwrap();
2850            assert_eq!(read_str(&out), "one\n\ntwo\n");
2851        }
2852
2853        #[test]
2854        fn f22_large_file_filtered_extraction() {
2855            // REQ-TAG-NF-002 / F22: ~1 MiB source alternating a/b tags;
2856            // filtering on `a` emits exactly the a-tagged lines
2857            let tmp = TempDir::new("f22");
2858            let mut content = String::new();
2859            let mut expected = String::new();
2860            for i in 0..20_000 {
2861                let text = format!("line {i} {}\n", "x".repeat(40));
2862                let tag = if i % 2 == 0 { "a" } else { "b" };
2863                let _ = write!(content, "////{tag} {text}");
2864                if tag == "a" {
2865                    expected.push_str(&text);
2866                }
2867            }
2868            assert!(content.len() >= 1_000_000, "source should be ~1 MiB");
2869            let src = tmp.write("big.rs", &content);
2870            let out = tmp.file("out.md");
2871            Docextract::new(&out)
2872                .unwrap()
2873                .input_filtered(&src, "a")
2874                .unwrap()
2875                .done()
2876                .unwrap();
2877            assert_eq!(read_str(&out), expected);
2878        }
2879
2880        #[test]
2881        fn f23_operation_after_done_returns_broken_pipe() {
2882            // REQ-TAG-F-008 / F23: `.input_filtered()` after `.done()` →
2883            // Err(BrokenPipe)
2884            let tmp = TempDir::new("f23");
2885            let src = tmp.write("f.rs", "////api a\n");
2886            let out = tmp.file("out.md");
2887            let mut builder = Docextract::new(&out).unwrap();
2888            builder.done().unwrap();
2889            let Err(err) = builder.input_filtered(&src, "api") else {
2890                panic!("expected error after done()");
2891            };
2892            assert_eq!(err.kind(), std::io::ErrorKind::BrokenPipe);
2893        }
2894
2895        #[test]
2896        fn f24_blank_line_tagged_with_current_tag() {
2897            // REQ-TAG-F-001 / F24: a `////` verbatim blank line is created
2898            // with the current tag and emitted if that tag matches the filter
2899            let tmp = TempDir::new("f24");
2900            let src = tmp.write("f.rs", "////\n////api\n////\n");
2901            let out = tmp.file("out.md");
2902            Docextract::new(&out)
2903                .unwrap()
2904                .input_filtered(&src, "api")
2905                .unwrap()
2906                .done()
2907                .unwrap();
2908            assert_eq!(read_str(&out), "\n");
2909        }
2910
2911        #[test]
2912        fn f25_missing_file_warns_and_continues() {
2913            // REQ-TAG-F-005 / F25: missing file with `.input_filtered()` →
2914            // warning to stderr, returns Ok, processing continues
2915            let tmp = TempDir::new("f25");
2916            let valid = tmp.write("valid.rs", "////api kept\n");
2917            let out = tmp.file("out.md");
2918            let mut builder = Docextract::new(&out).unwrap();
2919            assert!(
2920                builder
2921                    .input_filtered(tmp.file("missing.rs"), "api")
2922                    .is_ok()
2923            );
2924            builder.input_filtered(&valid, "api").unwrap();
2925            builder.done().unwrap();
2926            assert_eq!(read_str(&out), "kept\n");
2927        }
2928
2929        #[test]
2930        fn f26_invalid_utf8_errors() {
2931            // REQ-TAG-F-005 / F26: invalid UTF-8 content →
2932            // Err(io::ErrorKind::InvalidData)
2933            let tmp = TempDir::new("f26");
2934            let src = tmp.write_bytes("binary.rs", b"//// \xFF\xFE not utf8\n");
2935            let out = tmp.file("out.md");
2936            let mut builder = Docextract::new(&out).unwrap();
2937            let Err(err) = builder.input_filtered(&src, "api") else {
2938                panic!("expected error for invalid UTF-8");
2939            };
2940            assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
2941            // The builder must remain usable after the error.
2942            builder.done().unwrap();
2943        }
2944    }
2945
2946    // -----------------------------------------------------------------
2947    // Code-lifting tests — specs/code-lifting-spec.md §8.1–8.7
2948    // Batch 1: S01-S18 (split), R01-R21 (resolve_placeholders),
2949    // U01-U05 (UTF-8 char counting) — leaf function tests.
2950    // Batch 2: E01-E18 (end-to-end + capture zone), EX01-EX08 (sed-like e2e),
2951    // F01-F06 (filter interaction), D01-D11 (parse_sed_placeholder).
2952    // -----------------------------------------------------------------
2953    mod code_lifting {
2954        use super::*;
2955
2956        // --- §8.1 try_split_code_capturing (S01–S10) ---
2957
2958        #[test]
2959        fn s01_basic_split() {
2960            // S01 (REQ-LIFT-F-001, F-002): simple split at `////`
2961            assert_eq!(
2962                try_split_code_capturing("code;  //// {{}}"),
2963                Some(("code;", "{{}}"))
2964            );
2965        }
2966
2967        #[test]
2968        fn s02_trailing_spaces_stripped_from_code() {
2969            // S02 (REQ-LIFT-F-001, F-003): trailing spaces before `////`
2970            // are NOT part of the captured code
2971            assert_eq!(
2972                try_split_code_capturing("    let x = 5;      //// {{}}"),
2973                Some(("    let x = 5;", "{{}}"))
2974            );
2975        }
2976
2977        #[test]
2978        fn s03_single_space_is_separator() {
2979            // S03 (REQ-LIFT-F-001, F-003): one space before `////` IS
2980            // the separator — not part of the captured code
2981            assert_eq!(
2982                try_split_code_capturing("fn foo() { //// {{}}"),
2983                Some(("fn foo() {", "{{}}"))
2984            );
2985        }
2986
2987        #[test]
2988        fn s04_tab_separator() {
2989            // S04 (REQ-LIFT-F-001): tab before `////` is the separator
2990            assert_eq!(
2991                try_split_code_capturing("code\t//// {{}}"),
2992                Some(("code", "{{}}"))
2993            );
2994        }
2995
2996        #[test]
2997        fn s05_empty_template() {
2998            // S05 (REQ-LIFT-F-002): no template after `////`
2999            assert_eq!(try_split_code_capturing("code  ////"), Some(("code", "")));
3000        }
3001
3002        #[test]
3003        fn s06_no_separator_after_slashes() {
3004            // S06 (REQ-LIFT-F-002): text directly after `////` (no space)
3005            // is the template
3006            assert_eq!(
3007                try_split_code_capturing("code  ////text"),
3008                Some(("code", "text"))
3009            );
3010        }
3011
3012        #[test]
3013        fn s07_rightmost_double_slash_wins() {
3014            // S07 (REQ-LIFT-F-001): two `////` — the rightmost preceded
3015            // by space/tab is the split point
3016            assert_eq!(
3017                try_split_code_capturing("code //// inner //// {{}}"),
3018                Some(("code //// inner", "{{}}"))
3019            );
3020        }
3021
3022        #[test]
3023        fn s08_double_slash_inside_string_literal() {
3024            // S08 (REQ-LIFT-F-001): `////` inside a string literal is
3025            // not the split point — the rightmost one wins
3026            assert_eq!(
3027                try_split_code_capturing("    let x = \"////\";  //// {{}}"),
3028                Some(("    let x = \"////\";", "{{}}"))
3029            );
3030        }
3031
3032        #[test]
3033        fn s09_many_trailing_spaces_stripped() {
3034            // S09 (REQ-LIFT-F-003): multiple trailing spaces before
3035            // `////` are all stripped from the captured code
3036            assert_eq!(
3037                try_split_code_capturing("code;      //// {{}}"),
3038                Some(("code;", "{{}}"))
3039            );
3040        }
3041
3042        #[test]
3043        fn s10_no_separator_before_slashes() {
3044            // S10 (REQ-LIFT-F-001): no space/tab before `////` — not a
3045            // code-capturing line
3046            assert_eq!(try_split_code_capturing("code////no-separator"), None);
3047        }
3048
3049        // --- §8.2 resolve_placeholders — `{{}}` and `{{N}}` (R01–R10) ---
3050
3051        #[test]
3052        fn r01_full_substitution_double_trim() {
3053            // R01 (REQ-LIFT-F-004): `{{}}` strips leading AND trailing
3054            // whitespace
3055            assert_eq!(resolve_placeholders("{{}}", "    let x = 5;"), "let x = 5;");
3056        }
3057
3058        #[test]
3059        fn r02_full_substitution_plain_code() {
3060            // R02 (REQ-LIFT-F-004): `{{}}` on code with no whitespace
3061            assert_eq!(resolve_placeholders("{{}}", "code"), "code");
3062        }
3063
3064        #[test]
3065        fn r03_full_substitution_empty_code() {
3066            // R03 (REQ-LIFT-F-004): `{{}}` with empty captured code
3067            assert_eq!(resolve_placeholders("{{}}", ""), "");
3068        }
3069
3070        #[test]
3071        fn r04_zero_removal() {
3072            // R04 (REQ-LIFT-F-005): `{{0}}` removes nothing
3073            assert_eq!(resolve_placeholders("{{0}}", "code"), "code");
3074        }
3075
3076        #[test]
3077        fn r05_remove_four_chars() {
3078            // R05 (REQ-LIFT-F-005): `{{4}}` removes the first 4 chars
3079            // (the 4 leading spaces)
3080            assert_eq!(resolve_placeholders("{{4}}", "    code"), "code");
3081        }
3082
3083        #[test]
3084        fn r06_remove_one_char() {
3085            // R06 (REQ-LIFT-F-005): `{{1}}` removes the first char
3086            assert_eq!(resolve_placeholders("{{1}}", "abc"), "bc");
3087        }
3088
3089        #[test]
3090        fn r07_n_greater_than_code_length() {
3091            // R07 (REQ-LIFT-F-005): `{{3}}` on 2-char code → empty
3092            assert_eq!(resolve_placeholders("{{3}}", "ab"), "");
3093        }
3094
3095        #[test]
3096        fn r08_n_much_greater_than_code_length() {
3097            // R08 (REQ-LIFT-F-005): `{{100}}` on 5-char code → empty
3098            assert_eq!(resolve_placeholders("{{100}}", "short"), "");
3099        }
3100
3101        #[test]
3102        fn r09_placeholder_with_surrounding_text() {
3103            // R09 (REQ-LIFT-F-004): placeholder embedded in template text
3104            assert_eq!(
3105                resolve_placeholders("prefix {{}} suffix", "code"),
3106                "prefix code suffix"
3107            );
3108        }
3109
3110        #[test]
3111        fn r10_same_code_multiple_placeholders() {
3112            // R10 (REQ-LIFT-F-004): same captured code substituted twice
3113            assert_eq!(resolve_placeholders("{{}} and {{}}", "X"), "X and X");
3114        }
3115
3116        // --- §8.3 UTF-8 character counting for `{{N}}` (U01–U05) ---
3117
3118        #[test]
3119        fn u01_multibyte_char_removed_by_count() {
3120            // U01 (REQ-LIFT-NF-002): é is 2 bytes but 1 char — `{{1}}`
3121            // removes it entirely
3122            assert_eq!(resolve_placeholders("{{1}}", "éabc"), "abc");
3123        }
3124
3125        #[test]
3126        fn u02_two_multibyte_chars_removed() {
3127            // U02 (REQ-LIFT-NF-002): é + à = 4 bytes but 2 chars
3128            assert_eq!(resolve_placeholders("{{2}}", "éàbc"), "bc");
3129        }
3130
3131        #[test]
3132        fn u03_astral_char_counts_once() {
3133            // U03 (REQ-LIFT-NF-002): 😀 is 4 bytes but 1 char; a+😀+b =
3134            // 3 chars — `{{3}}` removes all
3135            assert_eq!(resolve_placeholders("{{3}}", "a😀b"), "");
3136        }
3137
3138        #[test]
3139        fn u04_zero_removal_multibyte_unchanged() {
3140            // U04 (REQ-LIFT-NF-002): `{{0}}` leaves multibyte code intact
3141            assert_eq!(resolve_placeholders("{{0}}", "éabc"), "éabc");
3142        }
3143
3144        #[test]
3145        fn u05_n_greater_than_char_count() {
3146            // U05 (REQ-LIFT-NF-002): `{{4}}` on 3-char code → empty
3147            // (char counting, not bytes: a+😀+b = 3 chars)
3148            assert_eq!(resolve_placeholders("{{4}}", "a😀b"), "");
3149        }
3150
3151        // --- Helper-function scaffolding tests (contract pinning) ---
3152
3153        #[test]
3154        fn trim_leading_space_tab_strips_only_leading_ws() {
3155            // REQ-LIFT-F-004: leading space/tab stripped, empty stays empty
3156            assert_eq!(trim_leading_space_tab("  code"), "code");
3157            assert_eq!(trim_leading_space_tab("\tcode"), "code");
3158            assert_eq!(trim_leading_space_tab("code"), "code");
3159            assert_eq!(trim_leading_space_tab(""), "");
3160        }
3161
3162        // NOTE: D01/D02/D10 (parse_sed_placeholder extract/replace/unterminated)
3163        // are DEFERRED to batch 2. trim_trailing_space_tab is tested indirectly
3164        // via S02/S03/S09 (through try_split_code_capturing); {{N}} char removal
3165        // is covered by U01-U05 via resolve_placeholders. count_utf8_chars_prefix
3166        // is not in the spec ({{N}} uses captured_code.chars().skip(n).collect()).
3167
3168        #[test]
3169        fn unescape_delimiter_unescapes_only_delimiter() {
3170            // REQ-LIFT-F-008: `\` + delimiter → literal delimiter;
3171            // other backslash sequences pass through unchanged
3172            assert_eq!(unescape_delimiter("foo\\/bar", b'/'), "foo/bar");
3173            assert_eq!(unescape_delimiter("baz/qux", b'/'), "baz/qux");
3174        }
3175
3176        // --- §8.5 End-to-end extraction tests (E01–E17) ---
3177        //
3178        // Helper: parse a single-line input and assert entries match
3179        // `(tag, text, transient)` triples.
3180        fn assert_parse(input: &str, initial_tag: &str, expected: &[(&str, &str, bool)]) {
3181            let mut tags = HashSet::new();
3182            let entries = parse_doc_entries(&mut tags, input, initial_tag);
3183            assert_eq!(entries.len(), expected.len(), "entry count mismatch");
3184            for (entry, (tag, text, transient)) in entries.iter().zip(expected) {
3185                assert_eq!(&*entry.tag, *tag, "tag mismatch");
3186                assert_eq!(&*entry.text, *text, "text mismatch");
3187                assert_eq!(entry.transient, *transient, "transient mismatch");
3188            }
3189        }
3190
3191        #[test]
3192        fn e01_basic_substitution_with_double_trim() {
3193            // E01 (REQ-LIFT-F-001,F-002,F-004,F-010): {{}} double-trim.
3194            // Template "value: {{}}" starts with 'v' → tag directive
3195            // "value:" (transient), text from {{}} resolution.
3196            assert_parse(
3197                "    let x = 5;      //// value: {{}}\n",
3198                "lib",
3199                &[("value:", "let x = 5;\n", true)],
3200            );
3201        }
3202
3203        #[test]
3204        fn e02_n_placeholder_character_removal() {
3205            // E02 (REQ-LIFT-F-005): {{8}} removes first 8 UTF-8 chars
3206            assert_parse(
3207                "    let x = 5;      //// {{8}}\n",
3208                "lib",
3209                &[("lib", "x = 5;\n", false)],
3210            );
3211        }
3212
3213        #[test]
3214        fn e03_n_exceeds_code_length() {
3215            // E03 (REQ-LIFT-F-005): {{100}} on short code → empty
3216            assert_parse(
3217                "    let x = 5;      //// {{100}}\n",
3218                "lib",
3219                &[("lib", "\n", false)],
3220            );
3221        }
3222
3223        #[test]
3224        fn e04_code_capture_between_doc_lines() {
3225            // E04 (REQ-LIFT-F-004,F-010): code capture between doc lines
3226            assert_parse(
3227                "//// # Before\n    code;  //// {{}}\n//// # After\n",
3228                "lib",
3229                &[
3230                    ("lib", "# Before\n", false),
3231                    ("lib", "code;\n", false),
3232                    ("lib", "# After\n", false),
3233                ],
3234            );
3235        }
3236
3237        #[test]
3238        fn e05_back_to_back_code_captures() {
3239            // E05 (REQ-LIFT-F-004): multiple code-capturing lines
3240            assert_parse(
3241                "    a;  //// {{}}\n    b;  //// {{}}\n",
3242                "lib",
3243                &[("lib", "a;\n", false), ("lib", "b;\n", false)],
3244            );
3245        }
3246
3247        #[test]
3248        fn e06_template_with_no_placeholder() {
3249            // E06 (REQ-LIFT-F-010): template with no {{}}.
3250            // Template "just text" starts with 'j' → tag directive
3251            // "just" (transient), text is "text\n".
3252            assert_parse(
3253                "    code;  //// just text\n",
3254                "lib",
3255                &[("just", "text\n", true)],
3256            );
3257        }
3258
3259        #[test]
3260        fn e07_empty_template() {
3261            // E07 (REQ-LIFT-F-010): empty template — just the line ending
3262            assert_parse("    code;  ////\n", "lib", &[("lib", "\n", false)]);
3263        }
3264
3265        #[test]
3266        fn e08_multiple_placeholders() {
3267            // E08 (REQ-LIFT-F-004): template "a{{}}b{{}}c" starts with 'a',
3268            // no space/tab → persistent switch to tag "a{{}}b{{}}c", no entry.
3269            assert_parse("    X;  //// a{{}}b{{}}c\n", "lib", &[]);
3270        }
3271
3272        #[test]
3273        fn e09_unterminated_double_brace() {
3274            // E09 (REQ-LIFT-F-004): unterminated {{ emitted literally.
3275            // Template "text {{ oops" starts with 't' → tag directive
3276            // "text" (transient), text is "{{ oops\n".
3277            assert_parse(
3278                "    X;  //// text {{ oops\n",
3279                "lib",
3280                &[("text", "{{ oops\n", true)],
3281            );
3282        }
3283
3284        #[test]
3285        fn e10_code_capture_with_tag_directive() {
3286            // E10 (REQ-LIFT-F-010): code capture under tag directive
3287            assert_parse(
3288                "////foo\n    code;  //// {{}}\n",
3289                "lib",
3290                &[("foo", "code;\n", false)],
3291            );
3292        }
3293
3294        #[test]
3295        fn e11_backward_compat_doc_lines_only() {
3296            // E11 (REQ-LIFT-C-004): only doc lines — output unchanged
3297            assert_parse(
3298                "//// Hello\n//// World\n",
3299                "lib",
3300                &[("lib", "Hello\n", false), ("lib", "World\n", false)],
3301            );
3302        }
3303
3304        #[test]
3305        fn e12_backward_compat_doc_with_code() {
3306            // E12 (REQ-LIFT-C-004): doc lines + regular code (non-capturing)
3307            assert_parse(
3308                "//// Doc\nlet x = 5;\n//// More\n",
3309                "lib",
3310                &[("lib", "Doc\n", false), ("lib", "More\n", false)],
3311            );
3312        }
3313
3314        #[test]
3315        fn e13_doc_line_with_trailing_slashes_not_code_capture() {
3316            // E13 (REQ-LIFT-C-004): //// line with trailing //// is a doc line
3317            assert_parse(
3318                "//// This text ends with ////\n",
3319                "lib",
3320                &[("lib", "This text ends with ////\n", false)],
3321            );
3322        }
3323
3324        #[test]
3325        fn e14_tag_directive_not_code_capture() {
3326            // E14 (REQ-LIFT-C-004): tag directive not treated as code capture
3327            assert_parse("////foo bar\n", "lib", &[("foo", "bar\n", true)]);
3328        }
3329
3330        #[test]
3331        fn e15_crlf_preserved() {
3332            // E15 (REQ-LIFT-F-010): CRLF preserved in code-capturing entry
3333            assert_parse(
3334                "code;  //// {{}}\r\n",
3335                "lib",
3336                &[("lib", "code;\r\n", false)],
3337            );
3338        }
3339
3340        #[test]
3341        fn e16_no_separator_before_slashes() {
3342            // E16 (REQ-LIFT-F-001): no space/tab before //// → skipped
3343            assert_parse("code////no-separator\n", "lib", &[]);
3344        }
3345
3346        #[test]
3347        #[should_panic(expected = "reserved placeholder form")]
3348        fn e17_reserved_form_panics() {
3349            // E17 (REQ-LIFT-F-009): reserved form {{abc}} panics
3350            let mut tags = HashSet::new();
3351            let _entries = parse_doc_entries(&mut tags, "code;  //// {{abc}}\n", "lib");
3352        }
3353
3354        // --- §8.5a Capture zone continuation (E18) ---
3355
3356        #[test]
3357        fn e18_capture_zone_continuation() {
3358            // E18: deeper-indented //// line inside a capture zone is
3359            // treated as code-capturing suffix, not a doc line.
3360            // Captured code is empty (whitespace before ////);
3361            // placeholders resolve with empty code.
3362            //
3363            // Input mimics the user's example: a code block inside
3364            // ``` fences with code-capturing lines and a continuation.
3365            assert_parse(
3366                concat!(
3367                    "//// lets show the internal code\n",
3368                    "//// ```\n",
3369                    "    code  //// {{}}\n",
3370                    "        //// {{4}} suffix\n",
3371                    "    more  //// {{}}\n",
3372                    "//// ```\n",
3373                ),
3374                "lib",
3375                &[
3376                    ("lib", "lets show the internal code\n", false),
3377                    ("lib", "```\n", false),
3378                    ("lib", "code\n", false),
3379                    // continuation: {{4}} on empty → empty, then " suffix"
3380                    ("lib", " suffix\n", false),
3381                    ("lib", "more\n", false),
3382                    ("lib", "```\n", false),
3383                ],
3384            );
3385        }
3386
3387        // --- §8.5b Tag-directive on code-capturing templates (E19–E22) ---
3388
3389        #[test]
3390        fn e19_transient_tag_on_code_capture() {
3391            // E19: user's exact example — transient tag on code-capturing
3392            // template with {{}} placeholder resolution.
3393            // `constants code: {{}}` → tag="constants", transient, text="code: <captured>\n"
3394            assert_parse(
3395                concat!(
3396                    "//// lets show the internal code\n",
3397                    "//// ```\n",
3398                    "fn foo() {\n",
3399                    "    const FOO:i32=0;   ////constants code: {{}}\n",
3400                    "    let x=1;                     //// {{4}}\n",
3401                    "                                     //// {{4}}\n",
3402                    "    println!(\"{x}\");        //// {{4}}\n",
3403                    "}\n",
3404                    "//// ```\n",
3405                ),
3406                "lib",
3407                &[
3408                    ("lib", "lets show the internal code\n", false),
3409                    ("lib", "```\n", false),
3410                    // template "constants code: {{}}" → tag="constants", transient, text="code: const FOO:i32=0;\n"
3411                    ("constants", "code: const FOO:i32=0;\n", true),
3412                    // "    let x=1;" → {{4}} removes first 4 chars → "let x=1;\n"
3413                    ("lib", "let x=1;\n", false),
3414                    // continuation: "    //// {{4}}" → {{4}} on empty → "" → just newline
3415                    ("lib", "\n", false),
3416                    // "    println!(\"{x}\");" → {{4}} → "println!(\"{x}\");\n"
3417                    ("lib", "println!(\"{x}\");\n", false),
3418                    ("lib", "```\n", false),
3419                ],
3420            );
3421        }
3422
3423        #[test]
3424        fn e20_persistent_tag_on_code_capture() {
3425            // E20: persistent tag switch on code-capture template.
3426            // `////mytag` (no space after tag) → persistent switch, no entry.
3427            // The next line captures under the new tag.
3428            assert_parse(
3429                concat!(
3430                    "//// before\n",
3431                    "    code;  ////mytag\n", // persistent switch → mytag
3432                    "    more;  //// {{}}\n", // now under tag "mytag"
3433                ),
3434                "lib",
3435                &[
3436                    ("lib", "before\n", false),
3437                    // "////mytag" (no space after tag) → persistent switch, no entry
3438                    // "more;  //// {{}}" → tag="mytag", text="more;\n"
3439                    ("mytag", "more;\n", false),
3440                ],
3441            );
3442        }
3443
3444        #[test]
3445        fn e21_transient_then_persistent_on_code_capture() {
3446            // E21: transient tag then persistent switch sequence on code-capture.
3447            assert_parse(
3448                concat!(
3449                    "    a;  ////tag1 {{}}\n", // transient: tag=tag1, text="a;\n"
3450                    "    b;  ////tag2\n",      // persistent switch → tag2 (no entry)
3451                    "    c;  //// {{}}\n",     // under tag2: text="c;\n"
3452                ),
3453                "lib",
3454                &[
3455                    ("tag1", "a;\n", true),
3456                    // persistent switch "tag2" → no entry
3457                    ("tag2", "c;\n", false),
3458                ],
3459            );
3460        }
3461
3462        #[test]
3463        fn e22_continuation_with_persistent_tag() {
3464            // E22: continuation line with persistent tag switch.
3465            assert_parse(
3466                concat!(
3467                    "    code;  //// {{}}\n", // zone at indent 4
3468                    "        ////mytag\n",    // deeper indent → continuation, persistent switch
3469                    "        //// {{}}\n",    // continuation under mytag: {{}} on empty → ""
3470                ),
3471                "lib",
3472                &[
3473                    ("lib", "code;\n", false),
3474                    // persistent switch "mytag" → no entry
3475                    // continuation {{}} on empty → empty
3476                    ("mytag", "\n", false),
3477                ],
3478            );
3479        }
3480
3481        // --- §8.7 Filter interaction tests (F01–F05) ---
3482
3483        #[test]
3484        fn f01_code_capture_matches_output_filter() {
3485            // F01 (REQ-LIFT-F-010): code-capture entry tagged chapter1,
3486            // matches output filter chapter1
3487            let tmp = TempDir::new("lift_f01");
3488            let src = tmp.write("f.rs", "////chapter1\n    code;  //// {{}}\n");
3489            let out = tmp.file("out.md");
3490            Docextract::new(&out)
3491                .unwrap()
3492                .filter_output(Some("chapter1"))
3493                .unwrap()
3494                .input(&src)
3495                .unwrap()
3496                .done()
3497                .unwrap();
3498            assert_eq!(read_str(&out), "code;\n");
3499        }
3500
3501        #[test]
3502        fn f02_code_capture_filtered_out_by_tag() {
3503            // F02 (REQ-LIFT-F-010): code-capture entry tagged chapter2,
3504            // filter chapter1 → filtered out
3505            let tmp = TempDir::new("lift_f02");
3506            let src = tmp.write("f.rs", "////chapter2\n    code;  //// {{}}\n");
3507            let out = tmp.file("out.md");
3508            Docextract::new(&out)
3509                .unwrap()
3510                .filter_output(Some("chapter1"))
3511                .unwrap()
3512                .input(&src)
3513                .unwrap()
3514                .done()
3515                .unwrap();
3516            assert_eq!(read_str(&out), "");
3517        }
3518
3519        #[test]
3520        fn f03_unfiltered_emits_both() {
3521            // F03 (REQ-LIFT-F-010): no filters — both doc and code-capture
3522            // entries emitted
3523            let tmp = TempDir::new("lift_f03");
3524            let src = tmp.write("f.rs", "//// Doc\n    code;  //// {{}}\n");
3525            let out = tmp.file("out.md");
3526            Docextract::new(&out)
3527                .unwrap()
3528                .input(&src)
3529                .unwrap()
3530                .done()
3531                .unwrap();
3532            assert_eq!(read_str(&out), "Doc\ncode;\n");
3533        }
3534
3535        #[test]
3536        fn f04_input_filtered_code_capture() {
3537            // F04 (REQ-LIFT-F-010): input_filtered(api) — only api-tagged
3538            // entries emitted. Use persistent tag switch ////api (no text)
3539            // so subsequent lines carry the api tag.
3540            // "    code;  //// captured": template "captured" → persistent
3541            // switch to tag "captured" (no entry), then ////core text is
3542            // transient — filtered out by "api".
3543            let tmp = TempDir::new("lift_f04");
3544            let src = tmp.write(
3545                "f.rs",
3546                "////api\n//// doc\n    code;  //// captured\n////core text\n",
3547            );
3548            let out = tmp.file("out.md");
3549            Docextract::new(&out)
3550                .unwrap()
3551                .input_filtered(&src, "api")
3552                .unwrap()
3553                .done()
3554                .unwrap();
3555            assert_eq!(read_str(&out), "doc\n");
3556        }
3557
3558        #[test]
3559        fn f05_code_capture_is_persistent() {
3560            // F05 (REQ-LIFT-F-010): templates starting with non-`{` characters
3561            // are now parsed as tag directives. "captured" → persistent switch
3562            // (no entry). The transient "t" entry is skipped in unfiltered mode.
3563            // Result: empty output.
3564            let tmp = TempDir::new("lift_f05");
3565            let src = tmp.write("f.rs", "////t transient\n    code;  //// captured\n");
3566            let out = tmp.file("out.md");
3567            Docextract::new(&out)
3568                .unwrap()
3569                .input(&src)
3570                .unwrap()
3571                .done()
3572                .unwrap();
3573            // transient "t" entry skipped; no other entries → empty
3574            assert_eq!(read_str(&out), "");
3575        }
3576
3577        #[test]
3578        fn f06_code_capture_carries_tag_and_responds_to_filter() {
3579            // F06: verify that tag directives on code-capturing templates
3580            // respond to output filtering. Template "captured" → persistent
3581            // switch to tag "captured" (no entry), followed by doc line.
3582            let tmp = TempDir::new("lift_f06");
3583            let src = tmp.write(
3584                "f.rs",
3585                concat!("////detail\n", "    code;  //// captured\n", "//// doc\n"),
3586            );
3587            let out = tmp.file("out.md");
3588            // Unfiltered: persistent switch "captured", then doc line
3589            // "doc" under "captured" tag → emitted
3590            Docextract::new(&out)
3591                .unwrap()
3592                .input(&src)
3593                .unwrap()
3594                .done()
3595                .unwrap();
3596            assert_eq!(read_str(&out), "doc\n");
3597            // Filtered for "detail": the doc line under "captured" is filtered out
3598            let out2 = tmp.file("out2.md");
3599            Docextract::new(&out2)
3600                .unwrap()
3601                .filter_output(Some("detail"))
3602                .unwrap()
3603                .input(&src)
3604                .unwrap()
3605                .done()
3606                .unwrap();
3607            assert_eq!(read_str(&out2), "");
3608        }
3609
3610        // --- §8.2a Sed-like resolve_placeholders (EX01–EX03) ---
3611
3612        #[cfg(feature = "regex")]
3613        #[test]
3614        fn ex01_replace_outputs_only_substitution() {
3615            // EX01 (REQ-LIFT-F-007): {{/regex/subst/}} outputs only the
3616            // expanded substitution. Non-matched text ("pub " in
3617            // "pub fn new;") is discarded.
3618            assert_eq!(
3619                resolve_placeholders("{{/fn (.*);/$1/}}", "pub fn new;"),
3620                "new"
3621            );
3622        }
3623
3624        #[cfg(feature = "regex")]
3625        #[test]
3626        fn ex02_replace_no_match_returns_empty() {
3627            // EX02 (REQ-LIFT-F-007): no regex match → empty string.
3628            assert_eq!(resolve_placeholders("{{/xxx/$1/}}", "pub fn new;"), "");
3629        }
3630
3631        #[cfg(feature = "regex")]
3632        #[test]
3633        fn ex03_extract_still_outputs_match() {
3634            // EX03 (REQ-LIFT-F-006): extract mode unchanged — outputs the
3635            // match text.
3636            assert_eq!(
3637                resolve_placeholders("{{/fn .*;/}}", "pub fn new;"),
3638                "fn new;"
3639            );
3640        }
3641    }
3642
3643    // -----------------------------------------------------------------
3644    // Global cache tests — specs/global-cache-spec.md §5
3645    //
3646    // RED phase: tests that exercise the thread-local global cache.
3647    // Expected to fail until the global cache implementation lands.
3648    // -----------------------------------------------------------------
3649    mod global_cache {
3650        use super::*;
3651        use std::rc::Rc;
3652
3653        // --- TC-01: Cache sharing across instances ---
3654
3655        /// Subprocess helper: runs the test binary with the given env var set,
3656        /// executing the same test function as the child.
3657        fn run_cache_sharing_subprocess(child_env: &str, test_name: &str) -> std::process::Output {
3658            let exe = std::env::current_exe().unwrap();
3659            std::process::Command::new(&exe)
3660                .env(child_env, "1")
3661                .arg("--exact")
3662                .arg(test_name)
3663                .arg("--nocapture")
3664                .output()
3665                .unwrap()
3666        }
3667
3668        #[test]
3669        fn tc01_cache_sharing_two_instances() {
3670            // REQ-CACHE-F-001, REQ-CACHE-F-005, REQ-CACHE-C-004
3671            if std::env::var_os("DOCEXTRACT_TC01_SUBPROCESS").is_some() {
3672                // Child: run the actual cache-sharing logic
3673                let tmp = TempDir::new("tc01");
3674                let src = tmp.write("in.rs", "////api doc\n");
3675                let out1 = tmp.file("out1.md");
3676                let out2 = tmp.file("out2.md");
3677                let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
3678
3679                Docextract::new(&out1)
3680                    .unwrap()
3681                    .input_filtered(&src, "api")
3682                    .unwrap()
3683                    .done()
3684                    .unwrap();
3685                Docextract::new(&out2)
3686                    .unwrap()
3687                    .input_filtered(&src, "api")
3688                    .unwrap()
3689                    .done()
3690                    .unwrap();
3691
3692                assert_eq!(read_str(&out1), "doc\n");
3693                assert_eq!(read_str(&out2), "doc\n");
3694                return;
3695            }
3696            let output = run_cache_sharing_subprocess(
3697                "DOCEXTRACT_TC01_SUBPROCESS",
3698                "tests::global_cache::tc01_cache_sharing_two_instances",
3699            );
3700            assert!(output.status.success(), "child failed: {:?}", output.status);
3701            let stdout = String::from_utf8_lossy(&output.stdout);
3702            let directive_count = stdout.matches("cargo:rerun-if-changed=").count();
3703            assert_eq!(
3704                directive_count, 1,
3705                "rerun-if-changed must be emitted exactly once across two instances, got: {stdout}"
3706            );
3707            assert!(
3708                String::from_utf8_lossy(&output.stderr).is_empty(),
3709                "no warnings expected"
3710            );
3711        }
3712
3713        #[test]
3714        fn tc01_cache_sharing_three_instances() {
3715            if std::env::var_os("DOCEXTRACT_TC01B_SUBPROCESS").is_some() {
3716                let tmp = TempDir::new("tc01b");
3717                let src = tmp.write("in.rs", "////api a\n");
3718                let out1 = tmp.file("out1.md");
3719                let out2 = tmp.file("out2.md");
3720                let out3 = tmp.file("out3.md");
3721                let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
3722
3723                Docextract::new(&out1)
3724                    .unwrap()
3725                    .input_filtered(&src, "api")
3726                    .unwrap()
3727                    .done()
3728                    .unwrap();
3729                Docextract::new(&out2)
3730                    .unwrap()
3731                    .input_filtered(&src, "api")
3732                    .unwrap()
3733                    .done()
3734                    .unwrap();
3735                Docextract::new(&out3)
3736                    .unwrap()
3737                    .input_filtered(&src, "api")
3738                    .unwrap()
3739                    .done()
3740                    .unwrap();
3741
3742                assert_eq!(read_str(&out1), "a\n");
3743                assert_eq!(read_str(&out2), "a\n");
3744                assert_eq!(read_str(&out3), "a\n");
3745                return;
3746            }
3747            let output = run_cache_sharing_subprocess(
3748                "DOCEXTRACT_TC01B_SUBPROCESS",
3749                "tests::global_cache::tc01_cache_sharing_three_instances",
3750            );
3751            assert!(output.status.success(), "child failed: {:?}", output.status);
3752            let stdout = String::from_utf8_lossy(&output.stdout);
3753            let directive_count = stdout.matches("cargo:rerun-if-changed=").count();
3754            assert_eq!(
3755                directive_count, 1,
3756                "rerun-if-changed must be emitted exactly once across three instances, got: {stdout}"
3757            );
3758        }
3759
3760        // --- TC-02: clear_cache ---
3761
3762        #[test]
3763        fn tc02_clear_cache_then_reparse() {
3764            if std::env::var_os("DOCEXTRACT_TC02_SUBPROCESS").is_some() {
3765                let tmp = TempDir::new("tc02");
3766                let src = tmp.write("in.rs", "////api doc\n");
3767                let out1 = tmp.file("out1.md");
3768                let out2 = tmp.file("out2.md");
3769                let _guard = OutDirGuard::with(Some(tmp.file("out_dir").as_os_str()));
3770
3771                Docextract::new(&out1)
3772                    .unwrap()
3773                    .input_filtered(&src, "api")
3774                    .unwrap()
3775                    .done()
3776                    .unwrap();
3777                Docextract::clear_cache();
3778                Docextract::new(&out2)
3779                    .unwrap()
3780                    .input_filtered(&src, "api")
3781                    .unwrap()
3782                    .done()
3783                    .unwrap();
3784
3785                assert_eq!(read_str(&out1), "doc\n");
3786                assert_eq!(read_str(&out2), "doc\n");
3787                return;
3788            }
3789            let output = run_cache_sharing_subprocess(
3790                "DOCEXTRACT_TC02_SUBPROCESS",
3791                "tests::global_cache::tc02_clear_cache_then_reparse",
3792            );
3793            assert!(output.status.success(), "child failed: {:?}", output.status);
3794            let stdout = String::from_utf8_lossy(&output.stdout);
3795            let directive_count = stdout.matches("cargo:rerun-if-changed=").count();
3796            assert_eq!(
3797                directive_count, 2,
3798                "rerun-if-changed must be emitted twice: before and after clear_cache, got: {stdout}"
3799            );
3800        }
3801
3802        #[test]
3803        fn tc02_clear_cache_on_empty_cache_noop() {
3804            // clear_cache() on empty cache → no panic, no error.
3805            Docextract::clear_cache();
3806            Docextract::clear_cache();
3807            // Multiple clears are idempotent.
3808        }
3809
3810        #[test]
3811        fn tc02_clear_cache_between_inputs_on_same_instance() {
3812            // clear_cache() between .input() calls on same instance
3813            // forces re-parse on second call.
3814            let tmp = TempDir::new("tc02c");
3815            let src = tmp.write("in.rs", "//// doc\n");
3816            let out = tmp.file("out.md");
3817
3818            let mut builder = Docextract::new(&out).unwrap();
3819            builder.input(&src).unwrap();
3820
3821            // Rewrite file to verify re-parse happens
3822            fs::write(&src, "//// new\n").unwrap();
3823
3824            // Clear cache — next input must re-read
3825            Docextract::clear_cache();
3826            builder.input(&src).unwrap();
3827            builder.done().unwrap();
3828
3829            // Since we re-read after clear, we get "new" not "doc"
3830            assert_eq!(read_str(&out), "doc\nnew\n");
3831        }
3832
3833        // --- TC-03: Path normalization ---
3834
3835        #[test]
3836        fn tc03_equivalent_paths_share_cache() {
3837            // REQ-CACHE-F-002
3838            // Same file accessed via canonical and original path shares cache.
3839            let tmp = TempDir::new("tc03");
3840            let src = tmp.write("file.rs", "//// hello\n");
3841            let out = tmp.file("out.md");
3842
3843            let mut builder = Docextract::new(&out).unwrap();
3844
3845            // First access: canonical path
3846            let canonical = std::fs::canonicalize(&src).unwrap();
3847            builder.input(&canonical).unwrap();
3848
3849            // Second access: original path — must be cache hit
3850            builder.input(&src).unwrap();
3851            builder.done().unwrap();
3852
3853            assert_eq!(read_str(&out), "hello\nhello\n");
3854        }
3855
3856        #[test]
3857        fn tc03_dot_slash_path_resolves() {
3858            // REQ-CACHE-F-002
3859            // `./path/to/file.rs` and `path/to/file.rs` share cache.
3860            let tmp = TempDir::new("tc03b");
3861            let subdir = tmp.file("subdir");
3862            fs::create_dir_all(&subdir).unwrap();
3863            let file_in_sub = subdir.join("file.rs");
3864            fs::write(&file_in_sub, "//// data\n").unwrap();
3865
3866            let out = tmp.file("out.md");
3867            let mut builder = Docextract::new(&out).unwrap();
3868
3869            // Change to the tmp directory so `./subdir/file.rs` resolves
3870            let orig_cwd = std::env::current_dir().unwrap();
3871            std::env::set_current_dir(tmp.0.as_path()).unwrap();
3872
3873            // First access with ./ prefix
3874            builder.input("./subdir/file.rs").unwrap();
3875
3876            // Second access without ./ prefix — must be cache hit
3877            builder.input("subdir/file.rs").unwrap();
3878            builder.done().unwrap();
3879
3880            // Restore CWD
3881            std::env::set_current_dir(orig_cwd).unwrap();
3882
3883            assert_eq!(read_str(&out), "data\ndata\n");
3884        }
3885
3886        // --- TC-04: Stdin caching ---
3887
3888        #[test]
3889        fn tc04_stdin_twice_on_same_instance() {
3890            // REQ-CACHE-F-007
3891            // Calling .stdin() twice should cache the second call (no re-read).
3892            // But in-process, .stdin() reads from the real stdin — this test
3893            // verifies that caching under the "-" key works. We use
3894            // .input_filtered("-", ...) which is the same code path.
3895            //
3896            // Since we can't inject stdin in a unit test, we verify
3897            // that the cache key "-" is recognized. We test via the
3898            // subprocess approach (TC-05 covers this via CLI).
3899        }
3900
3901        #[test]
3902        fn tc04_repeated_filtered_stdin_uses_cache() {
3903            // REQ-CACHE-F-007
3904            // Two reads of the same file via input_filtered — second is cache hit.
3905            let tmp = TempDir::new("tc04");
3906            let src = tmp.write("in.txt", "////api a\n////b b\n");
3907            let out = tmp.file("out.md");
3908
3909            let mut builder = Docextract::new(&out).unwrap();
3910            builder.input_filtered(&src, "api").unwrap();
3911            builder.input_filtered(&src, "b").unwrap();
3912            builder.done().unwrap();
3913
3914            assert_eq!(read_str(&out), "a\nb\n");
3915        }
3916
3917        // --- TC-06: Tag interning across instances ---
3918
3919        #[test]
3920        fn tc06_tag_interning_across_instances() {
3921            // REQ-CACHE-F-004
3922            // Tags from different parse calls across instances share the
3923            // same Rc<str> allocation via the global pool.
3924            let tmp = TempDir::new("tc06");
3925            let src1 = tmp.write("a.rs", "////foo bar\n");
3926            let src2 = tmp.write("b.rs", "////foo baz\n");
3927
3928            // Parse both files — entries from both should share tag "foo"
3929            // We need to access parsed entries to check Rc::ptr_eq.
3930            // Use parse_doc_entries directly.
3931            let content1 = fs::read_to_string(&src1).unwrap();
3932            let content2 = fs::read_to_string(&src2).unwrap();
3933            let mut tags = HashSet::new();
3934            let entries1 = parse_doc_entries(&mut tags, &content1, "a");
3935            let entries2 = parse_doc_entries(&mut tags, &content2, "b");
3936
3937            assert_eq!(entries1.len(), 1);
3938            assert_eq!(entries2.len(), 1);
3939            assert_eq!(&*entries1[0].tag, "foo");
3940            assert_eq!(&*entries2[0].tag, "foo");
3941            // Cross-instance: tags from two parse calls must share allocation
3942            assert!(
3943                Rc::ptr_eq(&entries1[0].tag, &entries2[0].tag),
3944                "tag 'foo' from two different parse calls must share the same Rc<str> allocation"
3945            );
3946        }
3947
3948        // --- TC-09: Error propagation (missing file) ---
3949
3950        #[test]
3951        fn tc09_missing_file_returns_ok_on_both_instances() {
3952            // REQ-CACHE-C-003
3953            // Missing file → canonicalize() fails → NotFound propagated.
3954            // Two instances both calling .input() on a missing file must
3955            // return Ok (warning to stderr) and not panic.
3956            let tmp = TempDir::new("tc09");
3957            let out1 = tmp.file("out1.md");
3958            let out2 = tmp.file("out2.md");
3959            let missing = tmp.file("does_not_exist.rs");
3960
3961            let mut builder1 = Docextract::new(&out1).unwrap();
3962            assert!(
3963                builder1.input(&missing).is_ok(),
3964                "missing file must return Ok (warning to stderr)"
3965            );
3966
3967            let mut builder2 = Docextract::new(&out2).unwrap();
3968            assert!(
3969                builder2.input(&missing).is_ok(),
3970                "second instance with missing file must also return Ok"
3971            );
3972
3973            builder1.done().unwrap();
3974            builder2.done().unwrap();
3975        }
3976
3977        // --- Backward compatibility: all existing tests pass ---
3978
3979        #[test]
3980        fn tc08_single_instance_output_unchanged() {
3981            // REQ-CACHE-C-001, REQ-CACHE-NF-002
3982            // Single-instance usage produces identical output to pre-cache.
3983            let tmp = TempDir::new("tc08");
3984            let src = tmp.write("in.rs", "//// Hello\n//// World\n");
3985            let out = tmp.file("out.md");
3986
3987            Docextract::new(&out)
3988                .unwrap()
3989                .input(&src)
3990                .unwrap()
3991                .done()
3992                .unwrap();
3993
3994            assert_eq!(read_str(&out), "Hello\nWorld\n");
3995        }
3996    }
3997}