raf-source 0.0.0

Workspace source index: a Tree file seam with disk and memory backends under canonical path containment.
Documentation
// SPDX-FileCopyrightText: 2026 Blackcat InformaticsĀ® Inc. <paudley@blackcatinformatics.ca>
// SPDX-License-Identifier: MIT OR Apache-2.0 OR MulanPSL-2.0

//! Run a load in a child process: the test binary runs itself.
//!
//! The child loads the selected text as the root file of a library through
//! `Workspace::load`, so the parse, the reading of its facts and the drop of
//! its syntax tree all run on the parse thread as in any load. A deep parse
//! can end the process, so the parent cannot judge it in process. The parent starts this same test binary, selects the one test that
//! calls [`run_child_if_requested`], and names the work in an environment
//! variable. The child prints one result line and exits. The parent maps what
//! happened to exactly one [`Outcome`]. A parse ends in a typed refusal or a
//! correct index; an abort is a failure of the parse that the judge reports.

use std::env;
use std::path::PathBuf;
use std::process::{Command, Stdio};

use raf_source::{LoadError, LoadErrorKind, MemoryTree, RelPath, Workspace};

/// The environment variable that names the work for a child.
const SELECTOR: &str = "RAF_SOURCE_CHILD";
/// Marks the child's one result line. The test harness may print its own
/// text before it on the same line.
const MARK: &str = "RAF_CHILD ";
/// The exit status of a typed refusal.
const REFUSED: i32 = 3;
/// The runtime's text when a thread runs out of stack.
const OVERFLOW_MESSAGE: &str = "has overflowed its stack";
/// The exit status of any other load error.
const FAILED: i32 = 4;

/// What became of one load.
#[derive(Debug, PartialEq, Eq)]
pub(crate) enum Outcome {
    /// The pre-scan refused the file, naming it and the budget.
    Refused { file: String, budget: String },
    /// The process exited 0 with this index.
    Index(Vec<String>),
    /// The process ended abnormally: a signal or a non-zero exit.
    Aborted { detail: String },
    /// The load failed in some other typed way.
    Failed { message: String },
}

/// The names of the items at the root of the crate `demo`, in path order.
pub(crate) fn symbols(workspace: &Workspace) -> Vec<String> {
    workspace
        .items()
        .filter_map(|item| item.path.strip_prefix("demo::"))
        .filter(|name| !name.contains("::"))
        .map(str::to_owned)
        .collect()
}

/// A package `demo` whose library root is `file`, holding `text`.
fn library(file: &RelPath, text: String) -> MemoryTree {
    let manifest = format!(
        "[package]\nname = \"demo\"\nversion = \"0.1.0\"\nedition = \"2021\"\n\n[lib]\npath = \"{file}\"\n"
    );
    [
        ("Cargo.toml".to_owned(), manifest),
        (file.to_string(), text),
    ]
    .into_iter()
    .collect()
}

/// In a child, the work it was started for; `None` in an ordinary run.
pub(crate) fn selector() -> Option<String> {
    env::var_os(SELECTOR).map(|selector| selector.to_string_lossy().into_owned())
}

/// In the child: load the selected text, print one line and exit. Without a
/// selector this returns at once, so the test that calls it passes when it
/// runs as an ordinary test.
pub(crate) fn run_child_if_requested(text_of: impl FnOnce(&str) -> String) {
    run_child_if_requested_with(text_of, |_, _| {});
}

/// Judge the same isolated load before publishing its existing outcome line.
pub(crate) fn run_child_if_requested_with(
    text_of: impl FnOnce(&str) -> String,
    compare: impl FnOnce(&MemoryTree, &Result<Workspace, LoadError>),
) {
    let Some(selector) = selector() else {
        return;
    };
    let (name, text) = (selector.clone(), text_of(&selector));
    let file = RelPath::new(&format!("{name}.rs")).expect("the selector is a plain name");
    let tree = library(&file, text);
    let loaded = Workspace::load(&tree, &["."]);
    compare(&tree, &loaded);
    let code = match loaded {
        Ok(workspace) => {
            println!("{MARK}index {}", symbols(&workspace).join(","));
            0
        }
        Err(error) => {
            if let LoadErrorKind::Budget { budget, .. } = &error.kind {
                println!("{MARK}refused {} {budget}", error.file);
                REFUSED
            } else {
                println!("{MARK}failed {error}");
                FAILED
            }
        }
    };
    std::process::exit(code);
}

/// Run the test named `test` of this binary as a child on `selector`.
pub(crate) fn run_child(test: &str, selector: &str) -> Outcome {
    let executable: PathBuf = env::current_exe().expect("the test binary has a path");
    let output = Command::new(executable)
        .args(["--exact", test, "--nocapture", "--test-threads=1"])
        .env(SELECTOR, selector)
        .env_remove("RUST_MIN_STACK")
        .stdin(Stdio::null())
        .output()
        .expect("start the child");
    let stdout = String::from_utf8_lossy(&output.stdout).into_owned();
    let stderr = String::from_utf8_lossy(&output.stderr).into_owned();
    classify(
        output.status.code(),
        died_by_signal(output.status),
        &stdout,
        &stderr,
    )
}

/// True when the process was ended by a signal.
#[cfg(unix)]
fn died_by_signal(status: std::process::ExitStatus) -> bool {
    use std::os::unix::process::ExitStatusExt as _;
    status.signal().is_some()
}

/// Without Unix there are no signals; the stack-overflow status is judged by
/// its exit code in [`classify`].
#[cfg(not(unix))]
fn died_by_signal(_status: std::process::ExitStatus) -> bool {
    false
}

/// The exit status the Windows runtime reports for a stack overflow.
const WINDOWS_STACK_OVERFLOW: i32 = 0xC000_00FD_u32.cast_signed();

/// Map what a child did to exactly one outcome.
///
/// * a result line with exit 0 is an index, and with exit 3 a refusal;
/// * an abort is only death by signal, the Windows stack-overflow status, or
///   the runtime's own stack-overflow message;
/// * everything else (a panic, an unknown selector, a non-zero exit without a
///   result line, exit 0 without one) is a failure.
pub(crate) fn classify(code: Option<i32>, signaled: bool, stdout: &str, stderr: &str) -> Outcome {
    let line = stdout
        .lines()
        .find_map(|line| line.split_once(MARK))
        .map(|(_, rest)| rest.to_owned());
    match (code, line) {
        (Some(0), Some(line)) => match line.strip_prefix("index ") {
            Some(list) => Outcome::Index(if list.is_empty() {
                Vec::new()
            } else {
                list.split(',').map(str::to_owned).collect()
            }),
            None => Outcome::Failed {
                message: format!("exit 0 with a line that is not an index: {line}"),
            },
        },
        (Some(REFUSED), Some(line)) => match line.strip_prefix("refused ") {
            Some(rest) => match rest.split_once(' ') {
                Some((file, budget)) => Outcome::Refused {
                    file: file.to_owned(),
                    budget: budget.to_owned(),
                },
                None => Outcome::Failed {
                    message: format!("a refusal without a budget: {rest}"),
                },
            },
            None => Outcome::Failed {
                message: format!("exit {REFUSED} with a line that is not a refusal: {line}"),
            },
        },
        (Some(FAILED), Some(line)) => Outcome::Failed { message: line },
        (code, line) => {
            let overflow = stderr.contains(OVERFLOW_MESSAGE);
            if line.is_none() && (signaled || overflow || code == Some(WINDOWS_STACK_OVERFLOW)) {
                Outcome::Aborted {
                    detail: format!("status {code:?}; stderr tail: {}", tail(stderr)),
                }
            } else {
                Outcome::Failed {
                    message: format!(
                        "status {code:?} is not an abort; result line {line:?}; stderr tail: {}",
                        tail(stderr)
                    ),
                }
            }
        }
    }
}

fn tail(text: &str) -> String {
    const KEEP: usize = 4000;
    let start = text.char_indices().rev().nth(KEEP).map_or(0, |(at, _)| at);
    text[start..].to_owned()
}

/// Judge an outcome against the allowed two. A refusal must name the file and
/// a budget; an index must equal `expected`. An abort and any other failure
/// are problems. Returns the problem, or `None` when the outcome is allowed.
pub(crate) fn problem(outcome: &Outcome, file: &str, expected: &[&str]) -> Option<String> {
    match outcome {
        Outcome::Refused {
            file: named,
            budget,
        } => {
            if named != file {
                Some(format!("refusal names {named:?}, not {file:?}"))
            } else if budget.is_empty() {
                Some("refusal does not name a budget".to_owned())
            } else {
                None
            }
        }
        Outcome::Index(found) => {
            if found
                .iter()
                .map(String::as_str)
                .eq(expected.iter().copied())
            {
                None
            } else {
                Some(format!(
                    "exit 0 with the index {found:?}, expected {expected:?}"
                ))
            }
        }
        Outcome::Aborted { detail } => Some(format!("the parse aborted: {detail}")),
        Outcome::Failed { message } => Some(format!("failed outside the two outcomes: {message}")),
    }
}