pdf-untangle 0.0.1

Untangle garbled PDF text: layout-aware extraction that reconstructs reading order, strips page furniture, and splits documents into structured, citable sections
Documentation
//! Declarative document-family profiles (TOML). All jurisdiction knowledge is
//! data, not code: adding a new document family means writing a profile.
//!
//! `jurisdiction`, `kind`, and `citation_template` are REQUIRED โ€” the first
//! two are the resolution routing keys downstream databases join on, and the
//! template is the single source of truth for the citation strings this
//! profile emits (signed off with the consuming system before a profile is
//! considered final; see docs/DESIGN.md ยง3).

use std::path::Path;

use anyhow::{Context, Result};
use serde::Deserialize;

/// Built-in profiles compiled into the crate (name โ†’ TOML source).
/// Drafts stay here until their citation template is signed off.
const BUILTINS: &[(&str, &str)] = &[("cnmi-rules", include_str!("../profiles/cnmi-rules.toml"))];

/// A document-family profile: how to find provisions in one family of PDFs.
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Profile {
    /// Human-readable profile name (matches the file stem for built-ins).
    pub name: String,
    /// Routing key: jurisdiction slug exactly as the consumer stores it
    /// (e.g. "northern_mariana_islands"). A wrong slug silently breaks
    /// downstream resolution, which is why it is declared here as data.
    pub jurisdiction: String,
    /// Routing key: "rule" or "statute".
    pub kind: String,
    /// Citation string template; `{num}` is replaced by the provision number
    /// (e.g. "NMI R. Civ. P. {num}").
    pub citation_template: String,
    /// DRAFT profiles have not had their citation template signed off yet.
    #[serde(default)]
    pub draft: bool,
    /// Regexes that recognize a provision-start heading line.
    pub heading_patterns: Vec<String>,
    /// Regexes that recognize history/credit lines (feed date parsing).
    #[serde(default)]
    pub history_patterns: Vec<String>,
    /// Date formats to try on history lines, in order (strftime-style).
    #[serde(default)]
    pub date_formats: Vec<String>,
    /// Regexes for blocks to skip entirely (committee notes, TOC, appendix).
    #[serde(default)]
    pub skip_patterns: Vec<String>,
    /// Provision numbers that are intentionally absent (reserved), so the
    /// structure-integrity sequence check does not flag them as gaps.
    #[serde(default)]
    pub expected_gaps: Vec<String>,
}

impl Profile {
    /// Parse a profile from TOML source.
    pub fn from_toml(src: &str) -> Result<Self> {
        let p: Profile = toml::from_str(src).context("invalid profile TOML")?;
        p.validate()?;
        Ok(p)
    }

    /// Load a profile from a TOML file on disk.
    pub fn from_path(path: &Path) -> Result<Self> {
        let src = std::fs::read_to_string(path)
            .with_context(|| format!("reading profile {}", path.display()))?;
        Self::from_toml(&src)
    }

    /// Load a built-in profile by name.
    pub fn builtin(name: &str) -> Result<Self> {
        let src = BUILTINS
            .iter()
            .find(|(n, _)| *n == name)
            .map(|(_, s)| *s)
            .with_context(|| {
                format!(
                    "no built-in profile {name:?} (known: {})",
                    builtin_names().join(", ")
                )
            })?;
        Self::from_toml(src)
    }

    fn validate(&self) -> Result<()> {
        anyhow::ensure!(
            !self.jurisdiction.is_empty(),
            "profile: jurisdiction must not be empty"
        );
        anyhow::ensure!(
            self.kind == "rule" || self.kind == "statute",
            "profile: kind must be \"rule\" or \"statute\", got {:?}",
            self.kind
        );
        anyhow::ensure!(
            self.citation_template.contains("{num}"),
            "profile: citation_template must contain {{num}}"
        );
        anyhow::ensure!(
            !self.heading_patterns.is_empty(),
            "profile: at least one heading pattern is required"
        );
        for pat in self
            .heading_patterns
            .iter()
            .chain(&self.history_patterns)
            .chain(&self.skip_patterns)
        {
            regex::Regex::new(pat).with_context(|| format!("invalid profile regex {pat:?}"))?;
        }
        Ok(())
    }
}

/// Names of all built-in profiles.
pub fn builtin_names() -> Vec<&'static str> {
    BUILTINS.iter().map(|(n, _)| *n).collect()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn builtin_cnmi_rules_parses() {
        let p = Profile::builtin("cnmi-rules").expect("built-in must parse");
        assert_eq!(p.jurisdiction, "northern_mariana_islands");
        assert_eq!(p.kind, "rule");
        assert!(p.citation_template.contains("{num}"));
        assert!(p.draft, "template not signed off yet โ€” must stay draft");
    }

    #[test]
    fn unknown_builtin_errors() {
        assert!(Profile::builtin("nope").is_err());
    }

    #[test]
    fn missing_routing_keys_rejected() {
        let err = Profile::from_toml(
            r#"
name = "x"
citation_template = "X {num}"
heading_patterns = ["^RULE"]
jurisdiction = "guam"
kind = "regulation"
"#,
        )
        .unwrap_err();
        assert!(err.to_string().contains("kind"));
    }

    #[test]
    fn bad_regex_rejected() {
        let err = Profile::from_toml(
            r#"
name = "x"
jurisdiction = "guam"
kind = "rule"
citation_template = "X {num}"
heading_patterns = ["("]
"#,
        )
        .unwrap_err();
        assert!(err.to_string().contains("invalid profile regex"));
    }
}