pdf-untangle 0.3.0

Untangle garbled PDF text: layout-aware extraction that reconstructs reading order, strips page furniture, and splits documents into structured, citable sections
Documentation
//! pdf-untangle CLI — thin wrapper over the pdf_untangle library.

use std::path::{Path, PathBuf};
use std::process::ExitCode;

use clap::{Parser, Subcommand};
use pdf_untangle::profile;

#[derive(Parser)]
#[command(
    name = "pdf-untangle",
    version,
    about = "Untangle garbled PDF text into structured sections"
)]
struct Cli {
    #[command(subcommand)]
    command: Command,
}

#[derive(Subcommand)]
enum Command {
    /// Extract structured provisions using a profile (JSONL output).
    Extract {
        pdf: PathBuf,
        /// Built-in profile name (see `profiles`) or a path to a .toml file.
        #[arg(long)]
        profile: String,
        /// Output path (default: stdout).
        #[arg(short, long)]
        out: Option<PathBuf>,
    },
    /// Emit clean, reading-ordered text (Layer 2 only; no profile needed).
    Text {
        pdf: PathBuf,
        /// Keep page furniture (headers/footers/page numbers) inline instead
        /// of stripping it.
        #[arg(long)]
        keep_furniture: bool,
        /// Emit the Line/Block layout model as JSON instead of plain text.
        #[arg(long)]
        json: bool,
    },
    /// Dump a page's positioned text runs (profile-authoring aid).
    Inspect {
        pdf: PathBuf,
        /// 1-based page number to dump.
        #[arg(long, default_value_t = 1)]
        page: u32,
        /// Emit machine-readable JSON instead of the table.
        #[arg(long)]
        json: bool,
    },
    /// List built-in profiles.
    Profiles,
    /// Dry-run a profile: coverage + structure-integrity report (exit != 0 on loss).
    Check {
        pdf: PathBuf,
        /// Built-in profile name (see `profiles`) or a path to a .toml file.
        #[arg(long)]
        profile: String,
        /// Emit the machine-readable report as JSON.
        #[arg(long)]
        json: bool,
    },
}

fn main() -> ExitCode {
    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info"))
        .format_timestamp(None)
        .init();
    let cli = Cli::parse();
    match cli.command {
        Command::Profiles => {
            for name in profile::builtin_names() {
                match profile::Profile::builtin(name) {
                    Ok(p) => {
                        let draft = if p.draft {
                            "  (draft — citation template pending sign-off)"
                        } else {
                            ""
                        };
                        println!(
                            "{name}: {} / {} — \"{}\"{draft}",
                            p.jurisdiction, p.kind, p.citation_template
                        );
                    }
                    Err(e) => eprintln!("{name}: BROKEN — {e:#}"),
                }
            }
            ExitCode::SUCCESS
        }
        Command::Inspect { pdf, page, json } => match inspect(&pdf, page, json) {
            Ok(()) => ExitCode::SUCCESS,
            Err(e) => {
                eprintln!("error: {e:#}");
                ExitCode::FAILURE
            }
        },
        Command::Text {
            pdf,
            keep_furniture,
            json,
        } => match text(&pdf, keep_furniture, json) {
            Ok(()) => ExitCode::SUCCESS,
            Err(e) => {
                eprintln!("error: {e:#}");
                ExitCode::FAILURE
            }
        },
        Command::Extract { pdf, profile, out } => match extract(&pdf, &profile, out.as_deref()) {
            Ok(()) => ExitCode::SUCCESS,
            Err(e) => {
                eprintln!("error: {e:#}");
                ExitCode::FAILURE
            }
        },
        Command::Check { pdf, profile, json } => match check(&pdf, &profile, json) {
            Ok(true) => ExitCode::SUCCESS,
            Ok(false) => ExitCode::FAILURE,
            Err(e) => {
                eprintln!("error: {e:#}");
                ExitCode::from(2)
            }
        },
    }
}

/// Resolve `--profile`: a path to a TOML file, or a built-in name.
fn resolve_profile(spec: &str) -> anyhow::Result<pdf_untangle::Profile> {
    let path = std::path::Path::new(spec);
    if spec.ends_with(".toml") || path.exists() {
        profile::Profile::from_path(path)
    } else {
        profile::Profile::builtin(spec)
    }
}

/// `pdf-untangle extract`: structured provisions as JSONL.
fn extract(pdf: &Path, profile_spec: &str, out: Option<&Path>) -> anyhow::Result<()> {
    let profile = resolve_profile(profile_spec)?;
    let doc = pdf_untangle::extract(pdf, &profile)?;
    log::info!(
        "{}: {} provision(s), line coverage {:.1}%",
        pdf.display(),
        doc.provisions.len(),
        doc.line_coverage * 100.0
    );
    for w in &doc.warnings {
        log::warn!("{w}");
    }
    match out {
        Some(path) => {
            let file = std::fs::File::create(path)
                .map_err(|e| anyhow::anyhow!("creating {}: {e}", path.display()))?;
            pdf_untangle::output::write_jsonl(std::io::BufWriter::new(file), &doc.provisions)?;
        }
        None => {
            pdf_untangle::output::write_jsonl(std::io::stdout().lock(), &doc.provisions)?;
        }
    }
    Ok(())
}

/// Coverage below this fraction fails `pdf-untangle check`.
const COVERAGE_FLOOR: f32 = 0.98;

/// `pdf-untangle check`: coverage + structure-integrity report.
/// Returns Ok(false) when the document fails the gates.
fn check(pdf: &Path, profile_spec: &str, json: bool) -> anyhow::Result<bool> {
    let profile = resolve_profile(profile_spec)?;
    let doc = pdf_untangle::extract(pdf, &profile)?;

    let mut failures: Vec<String> = Vec::new();
    if doc.line_coverage < COVERAGE_FLOOR {
        failures.push(format!(
            "line coverage {:.2}% is below the {:.0}% floor ({} unconsumed line(s))",
            doc.line_coverage * 100.0,
            COVERAGE_FLOOR * 100.0,
            doc.unconsumed_lines.len()
        ));
    }
    if doc.provisions.is_empty() && doc.empty_doc_marker.is_none() {
        failures.push("no provisions detected".to_string());
    }
    if !doc.sequence_duplicates.is_empty() {
        failures.push(format!(
            "duplicate provision number(s): {}",
            doc.sequence_duplicates.join(", ")
        ));
    }

    if json {
        let provisions: Vec<serde_json::Value> = doc
            .provisions
            .iter()
            .map(|p| {
                serde_json::json!({
                    "citation": p.citation,
                    "number": p.number,
                    "heading": p.heading,
                    "effective_date": p.effective_date,
                    "pages": p.pages,
                    "confidence": p.confidence,
                    "warnings": p.warnings,
                })
            })
            .collect();
        let report = serde_json::json!({
            "file": pdf.display().to_string(),
            "profile": profile.name,
            "pass": failures.is_empty(),
            "failures": failures,
            "line_coverage": doc.line_coverage,
            "lines_total": doc.lines_total,
            "lines_consumed": doc.lines_consumed,
            "lines_skipped": doc.lines_skipped,
            "lines_furniture": doc.lines_furniture,
            "unconsumed_lines": doc.unconsumed_lines,
            "empty_doc_marker": doc.empty_doc_marker,
            "sequence_gaps": doc.sequence_gaps,
            "sequence_duplicates": doc.sequence_duplicates,
            "warnings": doc.warnings,
            "provisions": provisions,
        });
        println!("{}", serde_json::to_string_pretty(&report)?);
        return Ok(failures.is_empty());
    }

    println!("{} — profile {}", pdf.display(), profile.name);
    match (doc.provisions.first(), doc.provisions.last()) {
        (Some(first), Some(last)) => println!(
            "provisions: {} ({} … {})",
            doc.provisions.len(),
            first.citation,
            last.citation
        ),
        _ => match &doc.empty_doc_marker {
            Some(m) => println!("provisions: 0 — recognized empty document ({m})"),
            None => println!("provisions: 0"),
        },
    }
    println!(
        "line coverage: {:.2}% ({}/{} accounted: {} consumed, {} skipped, {} furniture)",
        doc.line_coverage * 100.0,
        doc.lines_total - doc.unconsumed_lines.len(),
        doc.lines_total,
        doc.lines_consumed,
        doc.lines_skipped,
        doc.lines_furniture,
    );
    if doc.sequence_gaps.is_empty() && doc.sequence_duplicates.is_empty() {
        println!("sequence: ok");
    } else {
        println!(
            "sequence: {} gap(s) [{}], {} duplicate(s) [{}]",
            doc.sequence_gaps.len(),
            doc.sequence_gaps.join(", "),
            doc.sequence_duplicates.len(),
            doc.sequence_duplicates.join(", "),
        );
    }
    for w in &doc.warnings {
        println!("warning: {w}");
    }
    if !doc.unconsumed_lines.is_empty() {
        const SHOW: usize = 20;
        println!("unconsumed ({}):", doc.unconsumed_lines.len());
        for l in doc.unconsumed_lines.iter().take(SHOW) {
            println!("  {l}");
        }
        if doc.unconsumed_lines.len() > SHOW {
            println!(
                "  … and {} more (use --json for all)",
                doc.unconsumed_lines.len() - SHOW
            );
        }
    }
    if failures.is_empty() {
        println!("PASS");
        Ok(true)
    } else {
        for f in &failures {
            println!("FAIL: {f}");
        }
        Ok(false)
    }
}

/// `pdf-untangle text`: clean reading-ordered text (or the layout model).
fn text(pdf: &PathBuf, keep_furniture: bool, json: bool) -> anyhow::Result<()> {
    use anyhow::Context;
    use pdf_untangle::layout;

    let bytes = std::fs::read(pdf).with_context(|| format!("reading {}", pdf.display()))?;
    let (pages, backend) = pdf_untangle::extract::runs_with_backend(&bytes)?;
    let options = layout::LayoutOptions {
        strip_furniture: !keep_furniture,
    };
    let layout = layout::reconstruct_with(&pages, &options);
    if json {
        let doc = serde_json::json!({
            "file": pdf.display().to_string(),
            "backend": backend,
            "page_count": pages.len(),
            "blocks": layout.blocks,
            "furniture": layout.furniture,
        });
        println!("{}", serde_json::to_string_pretty(&doc)?);
    } else {
        print!("{}", layout.text());
    }
    Ok(())
}

/// `pdf-untangle inspect`: print one page's runs as a table or JSON.
fn inspect(pdf: &PathBuf, page: u32, json: bool) -> anyhow::Result<()> {
    use anyhow::Context;

    let bytes = std::fs::read(pdf).with_context(|| format!("reading {}", pdf.display()))?;
    let (pages, backend) = pdf_untangle::extract::runs_with_backend(&bytes)?;
    if page == 0 || page as usize > pages.len() {
        anyhow::bail!(
            "page {page} out of range: {} has {} page(s)",
            pdf.display(),
            pages.len()
        );
    }
    let p = &pages[page as usize - 1];

    if json {
        let doc = serde_json::json!({
            "file": pdf.display().to_string(),
            "backend": backend,
            "page": page,
            "page_count": pages.len(),
            "width": p.width,
            "height": p.height,
            "runs": p.runs,
        });
        println!("{}", serde_json::to_string_pretty(&doc)?);
        return Ok(());
    }

    println!(
        "{} — page {page}/{} — {:.0}x{:.0} pt — backend: {backend} — {} runs",
        pdf.display(),
        pages.len(),
        p.width,
        p.height,
        p.runs.len()
    );
    println!(
        "{:>4}  {:>7} {:>7} {:>7} {:>7}  {:>5}  {:2}  {:20}  text",
        "#", "x0", "y0", "x1", "y1", "size", "BI", "font"
    );
    for (i, run) in p.runs.iter().enumerate() {
        let style = format!(
            "{}{}",
            if run.bold { 'B' } else { '-' },
            if run.italic { 'I' } else { '-' }
        );
        let font = run.font.as_deref().unwrap_or("-");
        let font = if font.chars().count() > 20 {
            let truncated: String = font.chars().take(19).collect();
            format!("{truncated}…")
        } else {
            font.to_string()
        };
        println!(
            "{i:>4}  {:>7.1} {:>7.1} {:>7.1} {:>7.1}  {:>5.1}  {style}  {font:20}  {}",
            run.bbox.0,
            run.bbox.1,
            run.bbox.2,
            run.bbox.3,
            run.font_size,
            run.text.replace(['\n', '\r'], "\u{23ce}"),
        );
    }
    Ok(())
}