sherd 0.6.0

two-axis federation of SPEC.md and source over a dir DAG, for small-context local models
Documentation
//! `adopt` -- migrate a foreign single-file SPEC.md onto a federation, or propose the map for it.

use super::*;

/// `sherd adopt <dir> [--map FILE] [--check]` -- a foreign single-file
/// `SPEC.md` onto a federation.
///
/// Without `--map` this PROPOSES and writes nothing, exactly as `split` does
/// and for the same reason: which node owns which rule is a judgement
/// (`src/adopt:V2`). The proposal is printed AS the map file, so `sherd adopt
/// <dir> > map`, edit, `sherd adopt <dir> --map map` is the whole workflow.
///
/// Exit 1 means a migration is PENDING or was WRITTEN, which is `sync`'s
/// discipline one verb over: a tree that still has rows to move was not
/// clean when it was committed. A rerun over a migrated tree finds nothing
/// to move and exits 0 (`src/adopt:V6`).
pub(super) fn adopt_cmd(
    root: &Path,
    dir: &str,
    map: Option<&str>,
    dry: bool,
) -> ExitCode {
    // The NAMED node is the source (`src/adopt:V11`, `B6`): handing on the
    // root here is what made `adopt a/b` read the root spec.
    let node = adopt_node(root, &arg_dir(Some(dir), root));
    // BEFORE any count is printed (`src/adopt:V8`). A source this reader
    // cannot parse produces `0 rows read`, which in adopt's exit scheme means
    // "nothing to move" -- the opposite answer, in the same words, at the
    // same exit code (`src/adopt:B4`).
    match crate::adopt::unreadable_at(root, &node) {
        Ok(found) if !found.is_empty() => {
            return adopt_unreadable_at(root, &node, &found);
        }
        Ok(_) => {}
        Err(e) => return adopt_unusable(&e),
    }
    match map {
        None => adopt_propose_at(root, &node),
        Some(file) => adopt_with_map((root, &node), file, dry),
    }
}

/// Rows this reader could not parse, named with the line each sits on, and
/// exit 2 -- the USAGE code, because the file is in a form the verb does not
/// accept. Exit 0 keeps meaning "I read this and there is nothing to move".
/// As [`adopt_unreadable_at`], for the root spec. Dispatch always names a
/// node, so this is a test convenience and compiled as one, like
/// `args::repo_root`.
#[cfg(test)]
pub(super) fn adopt_unreadable(
    root: &Path,
    found: &[crate::spec::Unreadable],
) -> ExitCode {
    adopt_unreadable_at(root, ".", found)
}

/// The unreadable rows of `node`'s spec, named.
pub(super) fn adopt_unreadable_at(
    root: &Path,
    node: &str,
    found: &[crate::spec::Unreadable],
) -> ExitCode {
    let dir = if node == "." {
        root.to_path_buf()
    } else {
        root.join(node)
    };
    let path = dir.join("SPEC.md");
    eprintln!(
        "adopt: {}: {} id-shaped row(s) in a form this does not read",
        path.display(),
        found.len()
    );
    for u in found.iter().take(3) {
        eprintln!("  line {}: {}", u.line, u.text.trim());
    }
    if found.len() > 3 {
        eprintln!("  ... and {} more", found.len().saturating_sub(3));
    }
    eprintln!(
        "  a row opens its line with the id: `T1|status|task|cites`, \
         pipe-delimited (FORMAT.md). convert the table and run this again."
    );
    ExitCode::from(2)
}

/// PROPOSE, and print the proposal in the map's own format.
/// As [`adopt_propose_at`], for the root spec. A test convenience, as
/// [`adopt_unreadable`] is.
#[cfg(test)]
pub(super) fn adopt_propose(root: &Path) -> ExitCode {
    adopt_propose_at(root, ".")
}

/// The proposal splitting `node` (`src/adopt:V11`).
pub(super) fn adopt_propose_at(root: &Path, node: &str) -> ExitCode {
    let proposal = match crate::adopt::propose_at(root, node) {
        Ok(p) => p,
        Err(e) => return adopt_unusable(&e),
    };
    for p in &proposal.placements {
        println!("{} {}\t# {}", p.id, p.home, p.why.join(" "));
    }
    adopt_summary(&proposal);
    if proposal.placements.is_empty() {
        return ExitCode::SUCCESS;
    }
    ExitCode::from(1)
}

/// What the proposal found, on stderr so stdout stays a usable map file.
///
/// The unplaced rows are NAMED (`src/adopt:V2`). A row nobody claims is a
/// legitimate resting state at root, but it is a reader's decision to leave
/// it there, and a count that hid them would make the decision for them.
pub(super) fn adopt_summary(p: &crate::adopt::Proposal) {
    eprintln!(
        "  {} rows read · {} placed · {} unplaced",
        p.rows_in,
        p.placements.len(),
        p.unplaced.len()
    );
    if !p.unplaced.is_empty() {
        eprintln!("  staying at root: {}", p.unplaced.join(" "));
    }
}

/// Apply a map, or report what applying it would refuse.
pub(super) fn adopt_with_map(
    (root, node): (&Path, &str),
    file: &str,
    dry: bool,
) -> ExitCode {
    let map = match read_map_file(file) {
        Ok(m) => m,
        Err(e) => return adopt_unusable(&e),
    };
    if dry {
        return adopt_dry((root, node), &map);
    }
    match crate::adopt::apply_at(root, node, &map) {
        Ok(r) => adopt_wrote(&r),
        Err(e) => adopt_failed(&e),
    }
}

/// Read and parse a map file.
pub(super) fn read_map_file(
    file: &str,
) -> Result<std::collections::BTreeMap<String, String>, String> {
    let text = std::fs::read_to_string(file)
        .map_err(|e| format!("adopt: {file}: {e}"))?;
    crate::adopt::read_map(&text)
}

/// `--check`: every refusal, and nothing written.
pub(super) fn adopt_dry(
    (root, node): (&Path, &str),
    map: &std::collections::BTreeMap<String, String>,
) -> ExitCode {
    let refused = crate::adopt::refusals_at(root, node, map);
    for r in &refused {
        eprintln!("{r}");
    }
    if refused.is_empty() {
        eprintln!("  {} rows would move · nothing written", map.len());
        return ExitCode::SUCCESS;
    }
    ExitCode::from(1)
}

/// The counts a migration is judged by (`src/adopt:V1`), then exit 1 because
/// it WROTE.
pub(super) fn adopt_wrote(r: &crate::adopt::Report) -> ExitCode {
    for f in &r.files {
        println!("{f}");
    }
    for v in &r.carried {
        eprintln!("  carried in, not caused here: {v}");
    }
    eprintln!(
        "  {} rows read · {} moved · {} stayed at root · {} files written",
        r.rows_in,
        r.moved,
        r.stayed,
        r.files.len()
    );
    ExitCode::from(1)
}

/// A migration the verb READ and could not make: a refused map, a rejected
/// output, a failed write. 1, a verdict about this tree.
pub(super) fn adopt_failed(msg: &str) -> ExitCode {
    eprintln!("{msg}");
    ExitCode::from(1)
}

/// Input the verb could not read -- no source `SPEC.md`, a missing or
/// malformed map. There is no verdict to give, so 2 (`src/cli:V1`, `B11`):
/// 1 here means a migration is pending, and a wrapper acts on that.
pub(super) fn adopt_unusable(msg: &str) -> ExitCode {
    eprintln!("{msg}");
    ExitCode::from(2)
}

#[cfg(test)]
#[path = "tests/adopt.rs"]
mod tests;

/// `<dir>` as a citation names its node: a path from the root, `.` for the
/// root itself (`src/spec:V7`). `./a/` and `a` are one node.
pub(super) fn adopt_node(root: &Path, dir: &Path) -> String {
    let rel = dir.strip_prefix(root).unwrap_or(dir);
    let parts: Vec<String> = rel
        .components()
        .filter(|c| !matches!(c, std::path::Component::CurDir))
        .map(|c| c.as_os_str().to_string_lossy().into_owned())
        .collect();
    if parts.is_empty() {
        ".".into()
    } else {
        parts.join("/")
    }
}