frdt 0.2.3

Edit and inspect Resonite FrDT (.brson) documents without expanding them to JSON
Documentation
//! A slot subtree as a document of its own, with that slot as the root.
//!
//! - The ids are kept. The new root keeps its `ParentReference`, which now
//!   names nothing in the file, as every root's does.
//! - Only the assets the subtree uses (directly or through other assets) are
//!   kept.
//! - `Types` and `TypeVersions` are rebuilt from what remains.
//! - Every other root field (`VersionNumber`, `FeatureFlags`, fields this crate
//!   does not know) is copied as it is.
//! - A string in the copy equal to an id the source defines outside the
//!   subtree (and outside the kept assets) is unresolved: kept, refused, or
//!   written as null, as the [`UnresolvedPolicy`] says.

use std::collections::HashSet;

use crate::bson::{self, ARRAY, DOCUMENT, NULL, STRING};
use crate::datatree;
use crate::error::{Error, Result};
use crate::ids;
use crate::import::UnresolvedPolicy;
use crate::index::{self, Index};
use crate::typetable;

pub struct Outcome {
    pub bytes: Vec<u8>,
    pub index: Index,
    /// Source ids the copy refers to but does not contain, sorted.
    pub unresolved: Vec<String>,
}

/// `src` with the slot document at `slot_off` as its root.
pub fn extract(src: &[u8], slot_off: usize, policy: UnresolvedPolicy) -> Result<Outcome> {
    // Ids defined in the subtree, and strings it refers to (its own
    // `ParentReference` is not a reference the copy keeps).
    let mut defined: HashSet<&str> = HashSet::new();
    ids::visit_defined(src, slot_off, &mut |id| {
        defined.insert(id);
    })?;
    let mut queue: Vec<&str> = Vec::new();
    for el in bson::elements(src, slot_off)? {
        if el.key == "ParentReference" {
            continue;
        }
        if el.ty == STRING && !ids::is_id_key(el.key) {
            queue.push(bson::decode_string(el.value)?);
        } else if el.ty == DOCUMENT || el.ty == ARRAY {
            ids::visit_strings(src, el.value_at, &mut |s| queue.push(s))?;
        }
    }

    // Assets used by the subtree, then by those assets.
    let assets = asset_entries(src)?;
    let mut asset_of: std::collections::HashMap<&str, usize> = Default::default();
    for (i, &off) in assets.iter().enumerate() {
        ids::visit_defined(src, off, &mut |id| {
            asset_of.entry(id).or_insert(i);
        })?;
    }
    let mut kept = vec![false; assets.len()];
    let mut seen: HashSet<&str> = HashSet::new();
    while let Some(s) = queue.pop() {
        if !seen.insert(s) {
            continue;
        }
        if let Some(&i) = asset_of.get(s) {
            if !kept[i] {
                kept[i] = true;
                ids::visit_defined(src, assets[i], &mut |id| {
                    defined.insert(id);
                })?;
                ids::visit_strings(src, assets[i], &mut |s| queue.push(s))?;
            }
        }
    }

    // Referenced ids the source defines that the copy does not.
    let mut unresolved: HashSet<&str> = HashSet::new();
    ids::visit_defined(src, 0, &mut |id| {
        if seen.contains(id) && !defined.contains(id) {
            unresolved.insert(id);
        }
    })?;
    let mut unresolved: Vec<String> = unresolved.into_iter().map(str::to_string).collect();
    unresolved.sort();
    if policy == UnresolvedPolicy::Error && !unresolved.is_empty() {
        return Err(unresolved_error(&unresolved));
    }
    let nulls: HashSet<&str> = if policy == UnresolvedPolicy::Null {
        unresolved.iter().map(String::as_str).collect()
    } else {
        HashSet::new()
    };

    // The new root document: `Object` is the subtree, `Assets` the kept
    // entries, every other field as it was.
    let assets_key = datatree::asset_array(src)?.map(|el| el.key.to_string());
    let mut body = Vec::new();
    for el in bson::elements(src, 0)? {
        if el.key == "Object" {
            let slot = copy_doc(src, slot_off, &nulls, true)?;
            bson::push_element(&mut body, DOCUMENT, "Object", &slot);
        } else if Some(el.key) == assets_key.as_deref() {
            let mut arr = Vec::new();
            let mut n = 0usize;
            for (i, &off) in assets.iter().enumerate() {
                if kept[i] {
                    let entry = copy_doc(src, off, &nulls, false)?;
                    bson::push_element(&mut arr, DOCUMENT, &n.to_string(), &entry);
                    n += 1;
                }
            }
            bson::push_element(&mut body, ARRAY, el.key, &bson::finish_doc(&arr)?);
        } else {
            body.extend_from_slice(el.raw);
        }
    }
    let mut bytes = bson::finish_doc(&body)?;
    let index = index::build(&bytes)?;
    typetable::rebuild(&mut bytes, &index)?;
    bson::validate(&bytes)?;
    let index = index::build(&bytes)?;
    Ok(Outcome {
        bytes,
        index,
        unresolved,
    })
}

pub fn unresolved_error(unresolved: &[String]) -> Error {
    let shown: Vec<&str> = unresolved.iter().take(5).map(String::as_str).collect();
    Error::Invalid(format!(
        "{} unresolved reference(s) in the copy: {}{}",
        unresolved.len(),
        shown.join(", "),
        if unresolved.len() > shown.len() {
            ", ..."
        } else {
            ""
        }
    ))
}

fn asset_entries(buf: &[u8]) -> Result<Vec<usize>> {
    let Some(assets) = datatree::asset_array(buf)? else {
        return Ok(Vec::new());
    };
    if assets.ty != ARRAY {
        return Err(Error::Invalid("Assets is not an array".into()));
    }
    let mut out = Vec::new();
    for el in bson::elements(buf, assets.value_at)? {
        if el.ty != DOCUMENT {
            return Err(Error::Invalid("Assets entry is not a document".into()));
        }
        out.push(el.value_at);
    }
    Ok(out)
}

/// The document at `off`, with strings in `nulls` written as null. A plain
/// byte copy when there is nothing to replace. `root` keeps the document's
/// own `ParentReference`.
fn copy_doc(buf: &[u8], off: usize, nulls: &HashSet<&str>, root: bool) -> Result<Vec<u8>> {
    if nulls.is_empty() {
        let end = bson::doc_end(buf, off)?;
        return Ok(buf[off..end].to_vec());
    }
    let mut body = Vec::new();
    for el in bson::elements(buf, off)? {
        match el.ty {
            STRING
                if !ids::is_id_key(el.key)
                    && !(root && el.key == "ParentReference")
                    && nulls.contains(bson::decode_string(el.value)?) =>
            {
                bson::push_element(&mut body, NULL, el.key, &[]);
            }
            DOCUMENT | ARRAY => {
                let inner = copy_doc(buf, el.value_at, nulls, false)?;
                bson::push_element(&mut body, el.ty, el.key, &inner);
            }
            _ => body.extend_from_slice(el.raw),
        }
    }
    bson::finish_doc(&body)
}