bob/

project.rs

//! Eclipse project linked folders, as CS-Studio BOY workspaces use them.
//!
//! BOY screens name each other through the workspace project: a `.project`
//! file links folder names to real directories, so `../mks937a/gauge.opi`
//! from `proj/vacuum/x.opi` means the `mks937a` link of `proj`. A path
//! through such a project is kept as written (so `..` keeps working across
//! links), and [`locate`] finds the real file when it is opened.
//!
//! DLS modules have no `.project` on disk: the generated launcher
//! `runcss.sh` beside a module's screens lists the links, and CS-Studio
//! builds the project from them when it starts. Such a launcher is read (not
//! run) as a project of its own, in a virtual directory below the script:
//! `…/opi/opi/runcss.sh/vacuum_4-100` for project `vacuum_4-100`, which
//! cannot clash with a real file since `runcss.sh` is a file, not a folder.
//! See [`launcher_path`].

use std::collections::HashMap;
use std::io::Read;
use std::path::{Component, Path, PathBuf};
use std::sync::{LazyLock, Mutex};

/// A project's linked folders: name and real directory.
type Links = Vec<(String, PathBuf)>;

/// Folder links of each `.project` read so far, by project directory.
static PROJECTS: LazyLock<Mutex<HashMap<PathBuf, Links>>> = LazyLock::new(Default::default);

/// The DLS CS-Studio launcher that lists a module's links.
pub const LAUNCHER: &str = "runcss.sh";

/// The projects a launcher builds: name and links.
type Projects = Vec<(String, Links)>;

/// Projects of each launcher read so far, by script.
static LAUNCHERS: LazyLock<Mutex<HashMap<PathBuf, Projects>>> = LazyLock::new(Default::default);

/// The real file for `path`: `path` itself when it exists, else the path
/// through the linked folder of the Eclipse project it lies in, else `path`
/// with `.` and `..` removed (for the error message).
pub fn locate(path: &Path) -> PathBuf {
    locate_within(path, MAX_HOPS)
}

/// Most links followed from one project into another, so that projects
/// linking to each other (or to a missing folder of their own) end.
const MAX_HOPS: usize = 8;

fn locate_within(path: &Path, hops: usize) -> PathBuf {
    if path.exists() {
        return path.to_path_buf();
    }
    let path = normalize(path);
    let mut dir = path.parent();
    while let Some(d) = dir {
        if let Some(links) = links(d)
            && let Ok(rest) = path.strip_prefix(d)
            && let Some(Component::Normal(first)) = rest.components().next()
            && let Some((_, target)) = links.iter().find(|(name, _)| first == name.as_str())
        {
            let below = rest.strip_prefix(first).unwrap_or(Path::new(""));
            let real = target.join(below);
            // A link may point into another project.
            return if real.exists() || hops == 0 {
                real
            } else {
                locate_within(&real, hops - 1)
            };
        }
        dir = d.parent();
    }
    path
}

/// The virtual path of `real` in the project at `project_dir`: the first
/// linked folder holding it, so its `..` names resolve through the project.
pub fn virtual_path(project_dir: &Path, real: &Path) -> Option<PathBuf> {
    let canonical = |p: &Path| std::fs::canonicalize(p).unwrap_or_else(|_| p.to_path_buf());
    let targets: Vec<(String, PathBuf)> = links(project_dir)?
        .into_iter()
        .map(|(name, target)| (name, canonical(&target)))
        .collect();
    let find = |real: &Path| {
        targets.iter().find_map(|(name, target)| {
            let rest = real.strip_prefix(target).ok()?;
            Some(project_dir.join(name).join(rest))
        })
    };
    // A symlinked screen in a linked folder keeps its own name, as in
    // CS-Studio; one elsewhere (`~/x.opi -> …/opi/x.opi`) goes by where it
    // points.
    let dir = match real.parent() {
        Some(d) if !d.as_os_str().is_empty() => d,
        _ => Path::new("."),
    };
    real.file_name()
        .and_then(|name| find(&canonical(dir).join(name)))
        .or_else(|| find(&canonical(real)))
}

/// The project that `-p DIR` names: `dir` when its `.project` links
/// folders, else the (first) project of the launcher in `dir` (or `dir`
/// itself, when that is a `runcss.sh`), else `dir` with a `.project` that
/// links nothing.
pub fn project_dir(dir: &Path) -> Option<PathBuf> {
    let own = links(dir);
    if own.as_ref().is_some_and(|l| !l.is_empty()) {
        return Some(dir.to_path_buf());
    }
    let script = if dir.file_name().is_some_and(|n| n == LAUNCHER) {
        dir.to_path_buf()
    } else {
        dir.join(LAUNCHER)
    };
    match launcher_projects(&script).into_iter().next() {
        Some((project, _)) => Some(script.join(project)),
        None => own.map(|_| dir.to_path_buf()),
    }
}

/// How far above a screen its launcher may be: in the screen's own folder
/// (`opi/opi/x.opi`) or up to two above (`opi/opi/common/x.opi`).
const LAUNCHER_DEPTH: usize = 3;

/// The virtual path of the real BOY screen `real` through the projects of
/// the launcher in its folder or up to two above, as CS-Studio would open it
/// from there: `…/opi/opi/x.opi` is
/// `…/opi/opi/runcss.sh/vacuum_4-100/vacuum/x.opi`. `None` for a path that
/// is not a real file, one in no launcher's linked folders, and one that a
/// `.project` nearer than the launcher (or beside it) links: a `.project`
/// that links nothing, as many DLS modules have, does not count.
pub fn launcher_path(real: &Path) -> Option<PathBuf> {
    if !real.is_file() {
        return None;
    }
    let abs = normalize(&std::path::absolute(real).ok()?);
    for dir in abs.ancestors().skip(1).take(LAUNCHER_DEPTH) {
        if dir.join(".project").is_file() && virtual_path(dir, real).is_some() {
            return None;
        }
        let script = dir.join(LAUNCHER);
        if script.is_file() {
            return launcher_projects(&script)
                .iter()
                .find_map(|(project, _)| virtual_path(&script.join(project), real));
        }
    }
    None
}

/// Whether `dir` is a project: it holds a `.project` (which is not read),
/// or is one of a launcher's.
pub fn is_project(dir: &Path) -> bool {
    match launcher_of(dir) {
        Some(_) => links(dir).is_some(),
        None => dir.join(".project").is_file(),
    }
}

/// Whether `path` goes through a launcher's project.
pub fn through_launcher(path: &Path) -> bool {
    path.ancestors().any(|d| launcher_of(d).is_some())
}

/// The launcher whose project `dir` would be (`…/runcss.sh/PROJECT`).
fn launcher_of(dir: &Path) -> Option<&Path> {
    dir.parent()
        .filter(|s| s.file_name() == Some(LAUNCHER.as_ref()))
}

/// Forget the projects read so far, so that changed `.project` and
/// `runcss.sh` files are read again.
pub fn forget() {
    PROJECTS.lock().unwrap().clear();
    LAUNCHERS.lock().unwrap().clear();
}

/// The most of a `.project` file that is read.
const MAX_PROJECT_SIZE: u64 = 1 << 20;

/// The text file `path`, unless it is over [`MAX_PROJECT_SIZE`] bytes or not UTF-8.
fn read_capped(path: &Path) -> std::io::Result<String> {
    let mut bytes = Vec::new();
    std::fs::File::open(path)?
        .take(MAX_PROJECT_SIZE + 1)
        .read_to_end(&mut bytes)?;
    if bytes.len() as u64 > MAX_PROJECT_SIZE {
        log::warn!("{}: larger than 1 MiB, ignored", path.display());
        return Err(std::io::Error::other("file too large"));
    }
    String::from_utf8(bytes).map_err(std::io::Error::other)
}

/// Linked folders of `dir`'s project, by name, when `dir` holds a `.project`
/// or is a project of a launcher (`…/runcss.sh/PROJECT`).
pub fn links(dir: &Path) -> Option<Links> {
    if let Some(script) = launcher_of(dir) {
        let project = dir.file_name()?;
        return launcher_projects(script)
            .into_iter()
            .find(|(name, _)| project == name.as_str())
            .map(|(_, links)| links);
    }
    let mut projects = PROJECTS.lock().unwrap();
    if let Some(links) = projects.get(dir) {
        return Some(links.clone());
    }
    let text = read_capped(&dir.join(".project")).ok()?;
    let links = parse(&text, dir);
    projects.insert(dir.to_path_buf(), links.clone());
    Some(links)
}

/// The projects that the launcher `script` builds, as [`parse_launcher`]
/// finds them; none when it cannot be read.
fn launcher_projects(script: &Path) -> Projects {
    let mut launchers = LAUNCHERS.lock().unwrap();
    if let Some(projects) = launchers.get(script) {
        return projects.clone();
    }
    // Only a file: `x/runcss.sh/p` for a folder `runcss.sh` is a real path.
    if !script.is_file() {
        return Vec::new();
    }
    let Some(dir) = script.parent() else {
        return Vec::new();
    };
    let projects = read_capped(script)
        .map(|text| parse_launcher(&text, dir))
        .unwrap_or_default();
    launchers.insert(script.to_path_buf(), projects.clone());
    projects
}

/// DLS's table of named paths, which `configure-ioc s -p NAME` looks up.
const REDIRECT_TABLE: &str = "/dls_sw/prod/etc/redirector/redirect_table";

/// The linked folders that the launcher `text`, in `dir`, passes CS-Studio
/// as `links="REAL=/PROJECT/NAME,…"`, by project, in order. The script is
/// not run but read by [`Shell`], with `SCRIPT_DIR` as `dir`, `TOP` as
/// `dir/../../..` unless the script sets it, and `version` from
/// `$TOP/configure/VERSION` (else `dev`), as the DLS scripts set them.
fn parse_launcher(text: &str, dir: &Path) -> Projects {
    parse_launcher_with(text, dir, Path::new(REDIRECT_TABLE))
}

fn parse_launcher_with(text: &str, dir: &Path, table: &Path) -> Projects {
    let dir = normalize(&std::path::absolute(dir).unwrap_or_else(|_| dir.to_path_buf()));
    let mut shell = Shell {
        vars: HashMap::from([("SCRIPT_DIR".into(), dir.display().to_string())]),
        functions: HashMap::new(),
        table: table.to_path_buf(),
    };
    shell.set_top(&dir.join("../../.."));
    shell.run(text, SOURCE_DEPTH);
    let mut projects = Projects::new();
    for entry in shell
        .vars
        .get("links")
        .map_or("", String::as_str)
        .split(',')
    {
        let Some((real, virt)) = entry.trim().split_once('=') else {
            continue;
        };
        let Some((project, name)) = virt.trim_start_matches('/').split_once('/') else {
            continue;
        };
        let name = name.trim_end_matches('/');
        let real = normalize(Path::new(real));
        if project.is_empty() || name.is_empty() || name.contains('/') || !real.is_absolute() {
            continue;
        }
        let link = (name.to_string(), real);
        match projects.iter_mut().find(|(p, _)| p == project) {
            Some((_, links)) => links.push(link),
            None => projects.push((project.to_string(), vec![link])),
        }
    }
    projects
}

/// How deep `source` may nest in a launcher.
const SOURCE_DEPTH: usize = 4;

/// How deep `$(…)` commands may nest, functions calling functions.
const CALL_DEPTH: usize = 16;

/// Just enough of the shell to read a launcher without running it: plain
/// `name=value` lines, `source FILE`, and in `$(…)` the commands `join SEP
/// ARG…` (as `opi-versions` defines it), `configure-ioc s -p NAME` and the
/// script's functions whose body is one `echo`. Other commands (and so the
/// assignments using them) are skipped, as are function bodies.
struct Shell {
    vars: HashMap<String, String>,
    /// Each one-`echo` function's text.
    functions: HashMap<String, String>,
    table: PathBuf,
}

impl Shell {
    /// Set `TOP`, and `version` from its `configure/VERSION`.
    fn set_top(&mut self, top: &Path) {
        let version = std::fs::read_to_string(top.join("configure/VERSION"))
            .map(|v| v.trim().to_string())
            .unwrap_or_else(|_| "dev".into());
        self.vars.insert("TOP".into(), top.display().to_string());
        self.vars.insert("version".into(), version);
    }

    fn run(&mut self, text: &str, depth: usize) {
        let text = text.replace("\\\n", "");
        let mut lines = text.lines().map(str::trim);
        while let Some(line) = lines.next() {
            if let Some(name) = function_name(line) {
                let mut body = Vec::new();
                if !line.ends_with('{') && lines.next() != Some("{") {
                    continue;
                }
                for l in lines.by_ref() {
                    if l == "}" {
                        break;
                    }
                    if !l.is_empty() && !l.starts_with('#') {
                        body.push(l);
                    }
                }
                if let [echo] = body.as_slice()
                    && let Some(out) = echo.strip_prefix("echo ")
                {
                    self.functions
                        .insert(name.to_string(), out.trim().to_string());
                }
                continue;
            }
            let source = line
                .strip_prefix("source ")
                .or_else(|| line.strip_prefix(". "));
            if let Some(file) = source {
                if depth > 0
                    && let Some(file) = self.expand(unquote(file.trim()))
                    && let Ok(text) = std::fs::read_to_string(&file)
                {
                    self.run(&text, depth - 1);
                }
                continue;
            }
            let Some((name, value)) = line.split_once('=') else {
                continue;
            };
            let plain = !name.is_empty()
                && !name.starts_with(|c: char| c.is_ascii_digit())
                && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_');
            // `SCRIPT_DIR` and `version` keep the values set above, and
            // backquoted commands are not run.
            let fixed = ["SCRIPT_DIR", "version"].contains(&name);
            if !plain || fixed || value.contains('`') {
                continue;
            }
            let value = match value.strip_prefix('\'') {
                Some(v) => v.strip_suffix('\'').unwrap_or(v).to_string(),
                None => match self.expand(unquote(value)) {
                    Some(v) => v,
                    None => continue,
                },
            };
            if name == "TOP" {
                self.set_top(&normalize(Path::new(&value)));
            } else {
                self.vars.insert(name.to_string(), value);
            }
        }
    }

    /// `text` with `$name`, `${name}` (empty when unset) and `$(command)`
    /// replaced, as the shell would in double quotes; `None` when a command
    /// is not one [`Shell::command`] knows.
    fn expand(&self, text: &str) -> Option<String> {
        self.expand_with(text, &HashMap::new(), CALL_DEPTH)
    }

    /// [`Shell::expand`] with the positional `args` (`$1`…) too.
    fn expand_with(
        &self,
        text: &str,
        args: &HashMap<String, String>,
        depth: usize,
    ) -> Option<String> {
        let word = |c: char| c.is_ascii_alphanumeric() || c == '_';
        let mut out = String::with_capacity(text.len());
        let mut rest = text;
        while let Some(i) = rest.find('$') {
            out.push_str(&rest[..i]);
            let after = &rest[i + 1..];
            if let Some(inner) = after.strip_prefix('(') {
                let end = closing_paren(inner)?;
                out.push_str(self.command(&inner[..end], depth)?.trim_end_matches('\n'));
                rest = &inner[end + 1..];
                continue;
            }
            let (name, next) = match after.strip_prefix('{') {
                Some(braced) => match braced.split_once('}') {
                    Some((name, next)) => (name, next),
                    None => ("", after),
                },
                None => {
                    let end = after.find(|c| !word(c)).unwrap_or(after.len());
                    (&after[..end], &after[end..])
                }
            };
            if name.is_empty() {
                out.push('$');
            } else {
                let value = args.get(name).or_else(|| self.vars.get(name));
                out.push_str(value.map_or("", String::as_str));
            }
            rest = next;
        }
        out.push_str(rest);
        Some(out)
    }

    /// The output of the simple command `text`, if it is one we know.
    fn command(&self, text: &str, depth: usize) -> Option<String> {
        // A function calling itself must end.
        let depth = depth.checked_sub(1)?;
        let words = split_words(text)
            .into_iter()
            .map(|w| self.expand_with(unquote(w), &HashMap::new(), depth))
            .collect::<Option<Vec<_>>>()?;
        let (name, args) = words.split_first()?;
        match (name.as_str(), args) {
            ("join", [sep, rest @ ..]) => Some(rest.join(sep)),
            ("configure-ioc", [mode, flag, key])
                if ["s", "show"].contains(&mode.as_str()) && flag == "-p" =>
            {
                let table = std::fs::read_to_string(&self.table).ok()?;
                table.lines().find_map(|l| {
                    let (k, v) = l.split_once(' ')?;
                    (k == key).then(|| v.trim().to_string())
                })
            }
            _ => {
                let echo = self.functions.get(name)?;
                let args = args
                    .iter()
                    .enumerate()
                    .map(|(i, a)| ((i + 1).to_string(), a.clone()))
                    .collect();
                self.expand_with(unquote(echo), &args, depth)
            }
        }
    }
}

/// The function a line such as `name()`, `name() {` or `function name()`
/// starts.
fn function_name(line: &str) -> Option<&str> {
    let line = line.strip_prefix("function ").unwrap_or(line);
    let (name, rest) = line.split_once("()")?;
    let name = name.trim();
    let ok = !name.is_empty()
        && name
            .chars()
            .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
        && matches!(rest.trim(), "" | "{");
    ok.then_some(name)
}

/// `text` without one pair of surrounding double quotes.
fn unquote(text: &str) -> &str {
    text.strip_prefix('"')
        .and_then(|t| t.strip_suffix('"'))
        .unwrap_or(text)
}

/// Where the `)` closing a `$(` is in `text`, the text after the `(`.
fn closing_paren(text: &str) -> Option<usize> {
    let mut depth = 0;
    for (i, c) in text.char_indices() {
        match c {
            '(' => depth += 1,
            ')' if depth == 0 => return Some(i),
            ')' => depth -= 1,
            _ => {}
        }
    }
    None
}

/// The words of a command: split at blanks outside `$(…)` and double quotes.
fn split_words(text: &str) -> Vec<&str> {
    let mut words = Vec::new();
    let (mut start, mut depth, mut quoted) = (None, 0, false);
    for (i, c) in text.char_indices() {
        match c {
            '"' => quoted = !quoted,
            '(' => depth += 1,
            ')' => depth -= 1,
            c if c.is_whitespace() && depth == 0 && !quoted => {
                if let Some(s) = start.take() {
                    words.push(&text[s..i]);
                }
                continue;
            }
            _ => {}
        }
        start.get_or_insert(i);
    }
    if let Some(s) = start {
        words.push(&text[s..]);
    }
    words
}

/// `<link><name>…</name><location>…</location></link>` entries of the
/// `.project` in `dir` (or `<locationURI>`), resolved by [`location`].
fn parse(text: &str, dir: &Path) -> Links {
    if crate::element::depth(text) > crate::element::MAX_DEPTH {
        return Vec::new();
    }
    let Ok(doc) = roxmltree::Document::parse_with_options(
        text,
        roxmltree::ParsingOptions {
            nodes_limit: 1 << 16,
            ..Default::default()
        },
    ) else {
        return Vec::new();
    };
    doc.descendants()
        .filter(|n| n.has_tag_name("link"))
        .filter_map(|link| {
            let child = |name: &str| {
                link.children()
                    .find(|c| c.has_tag_name(name))
                    .and_then(|c| c.text())
                    .map(str::trim)
            };
            let name = child("name")?;
            let location = child("location").or_else(|| child("locationURI"))?;
            Some((name.to_string(), location_path(location, dir)?))
        })
        .collect()
}

/// The directory a link's location (or location URI) names, for the project
/// in `dir`: an absolute path, a `file:` URI, or one relative to the project
/// as `PROJECT_LOC/x` or `PARENT-2-PROJECT_LOC/x`. `None` for anything else
/// (`virtual:`, other variables or a bare relative path), which would
/// otherwise be taken relative to the working directory.
fn location_path(location: &str, dir: &Path) -> Option<PathBuf> {
    let project_relative = |rest: &str| {
        let (n, rest) = match rest.strip_prefix("PARENT-") {
            Some(r) => {
                let (n, r) = r.split_once("-PROJECT_LOC")?;
                (n.parse::<usize>().ok()?, r)
            }
            None => (0, rest.strip_prefix("PROJECT_LOC")?),
        };
        let rest = rest.strip_prefix('/').or(rest.is_empty().then_some(rest))?;
        // `absolute` keeps `..`, so `../proj` needs normalising before `parent`.
        let mut base = normalize(&std::path::absolute(dir).ok()?);
        for _ in 0..n {
            base = base.parent()?.to_path_buf();
        }
        Some(base.join(percent_decode(rest)))
    };
    let path = if let Some(uri) = location.strip_prefix("file:") {
        // file:/x, file:///x, or file://localhost/x.
        let path = match uri.strip_prefix("//") {
            Some(rest) => &rest[rest.find('/')?..],
            None => uri,
        };
        // Decoded first, as the drive may be escaped (`/C%3A/x`).
        let path = percent_decode(path);
        match path.to_str() {
            Some(p) => PathBuf::from(crate::source::file_url_path(p)),
            None => PathBuf::from(path),
        }
    } else if let Some(path) = project_relative(location) {
        path
    } else {
        PathBuf::from(location)
    };
    path.is_absolute().then_some(path)
}

/// `text` with `%xx` escapes decoded, as in a URI.
fn percent_decode(text: &str) -> std::ffi::OsString {
    let bytes = text.as_bytes();
    let mut out = Vec::with_capacity(bytes.len());
    let mut i = 0;
    while i < bytes.len() {
        let hex = bytes
            .get(i + 1..i + 3)
            .filter(|h| bytes[i] == b'%' && h.iter().all(u8::is_ascii_hexdigit))
            .and_then(|h| u8::from_str_radix(std::str::from_utf8(h).ok()?, 16).ok());
        match hex {
            Some(b) => {
                out.push(b);
                i += 3;
            }
            None => {
                out.push(bytes[i]);
                i += 1;
            }
        }
    }
    #[cfg(unix)]
    return std::os::unix::ffi::OsStringExt::from_vec(out);
    // Elsewhere (Windows, and the browser, which has no files anyway) paths
    // are text.
    #[cfg(not(unix))]
    return String::from_utf8_lossy(&out).into_owned().into();
}

/// `path` with `.` and `..` removed, without looking at the file system.
pub fn normalize(path: &Path) -> PathBuf {
    let mut out = PathBuf::new();
    for c in path.components() {
        match c {
            Component::CurDir => {}
            // `..` above the root is the root; above a relative start it
            // stays.
            Component::ParentDir => match out.components().next_back() {
                Some(Component::Normal(_)) => {
                    out.pop();
                }
                Some(Component::RootDir | Component::Prefix(_)) => {}
                _ => out.push(".."),
            },
            c => out.push(c),
        }
    }
    out
}

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

    fn tmp(name: &str) -> PathBuf {
        let dir = std::env::temp_dir().join(format!("bob-project-{name}-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        dir
    }

    #[test]
    fn finds_files_through_linked_folders() {
        let real = tmp("real");
        std::fs::write(real.join("x.opi"), "<display/>").unwrap();
        let proj = tmp("proj");
        std::fs::write(
            proj.join(".project"),
            format!(
                "<projectDescription><linkedResources>
                <link><name>a</name><type>2</type><location>{}</location></link>
                <link><name>u</name><type>2</type><locationURI>file:{}</locationURI></link>
                </linkedResources></projectDescription>",
                real.display(),
                real.display()
            ),
        )
        .unwrap();
        let x = real.join("x.opi");
        assert_eq!(locate(&proj.join("a/x.opi")), x);
        assert_eq!(locate(&proj.join("b/../a/x.opi")), x);
        assert_eq!(locate(&proj.join("u/x.opi")), x);
        assert_eq!(locate(&proj.join("a/./sub/../x.opi")), x);
        // Existing files and unknown links are left alone.
        assert_eq!(locate(&x), x);
        assert_eq!(locate(&proj.join("c/../q.opi")), proj.join("q.opi"));
        assert_eq!(virtual_path(&proj, &x), Some(proj.join("a/x.opi")));
        assert_eq!(virtual_path(&proj, Path::new("/elsewhere/y.opi")), None);
    }

    #[test]
    fn link_cycles_end() {
        let proj = tmp("cycle");
        std::fs::write(
            proj.join(".project"),
            format!(
                "<projectDescription><linkedResources>
                <link><name>a</name><location>{}</location></link>
                </linkedResources></projectDescription>",
                proj.join("a").display()
            ),
        )
        .unwrap();
        assert_eq!(locate(&proj.join("a/x.opi")), proj.join("a/x.opi"));
    }

    #[cfg(windows)]
    #[test]
    fn windows_link_locations() {
        let loc = |l: &str| location_path(l, Path::new(r"C:\w\proj"));
        assert_eq!(loc(r"D:\abs\opi"), Some(PathBuf::from(r"D:\abs\opi")));
        assert_eq!(
            loc("file:/D:/a%20b/opi"),
            Some(PathBuf::from(r"D:\a b\opi"))
        );
        assert_eq!(loc("file:///D%3A/opi"), Some(PathBuf::from(r"D:\opi")));
        assert_eq!(
            loc("PROJECT_LOC/sub"),
            Some(PathBuf::from(r"C:\w\proj\sub"))
        );
        assert_eq!(loc("/no/drive"), None);
    }

    #[cfg(unix)]
    #[test]
    fn link_locations_resolve_against_the_project() {
        let dir = Path::new("/w/proj");
        let loc = |l: &str| location_path(l, dir);
        assert_eq!(loc("/abs/opi"), Some(PathBuf::from("/abs/opi")));
        assert_eq!(loc("file:/a%20b/opi"), Some(PathBuf::from("/a b/opi")));
        assert_eq!(loc("file:///a/opi"), Some(PathBuf::from("/a/opi")));
        assert_eq!(loc("file://localhost/a"), Some(PathBuf::from("/a")));
        assert_eq!(loc("PROJECT_LOC/sub"), Some(PathBuf::from("/w/proj/sub")));
        assert_eq!(
            loc("PARENT-1-PROJECT_LOC/other%20x"),
            Some(PathBuf::from("/w/other x"))
        );
        // A relative project path with `..` climbs from its normalised form.
        let up = normalize(&std::path::absolute("..").unwrap());
        assert_eq!(
            location_path("PARENT-2-PROJECT_LOC/x", Path::new("../proj")),
            Some(up.parent().unwrap().join("x"))
        );
        for bad in [
            "virtual:/virtual",
            "WORKSPACE_LOC/x",
            "rel/dir",
            "PARENT-9-PROJECT_LOC/x",
        ] {
            assert_eq!(loc(bad), None, "{bad}");
        }
    }

    /// A DLS module's launcher, as generated, with the lines that matter.
    const RUNCSS: &str = r#"#!/bin/bash
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
TOP=${SCRIPT_DIR}/../../..
CSS_RUN_SCRIPT=$(configure-ioc s -p CSS-gui)
opifile="$1"
if [[ -z $opifile || $opifile == "-h" ]]; then
    exit 1
fi
if [ -e "${TOP}/configure/VERSION" ] ; then
    version="$(cat "${TOP}"/configure/VERSION)"
else
    version="dev"
fi
project=vac_${version}
module=vac
launch_opi=/${project}/${module}/$opifile

links="${SCRIPT_DIR}=${project}/${module},\
GAUGE=/${project}/gauge/,\
/nowhere=/${project}/sub/dir,\
relative/dir=/${project}/rel,\
OTHER=/elsewhere/other"

$CSS_RUN_SCRIPT -o "${launch_opi}" -s -l "$links" "$@"
"#;

    /// A module `top` with its screens (and launcher) in `top/vacApp/opi/opi`,
    /// and a module `gauge` it links to.
    fn module(name: &str, version: Option<&str>) -> (PathBuf, PathBuf, PathBuf) {
        let root = tmp(name);
        let top = root.join("top");
        let opi = top.join("vacApp/opi/opi");
        let gauge = root.join("gauge/opi");
        std::fs::create_dir_all(opi.join("common")).unwrap();
        std::fs::create_dir_all(&gauge).unwrap();
        if let Some(v) = version {
            std::fs::create_dir_all(top.join("configure")).unwrap();
            std::fs::write(top.join("configure/VERSION"), format!("{v}\n")).unwrap();
        }
        let script = RUNCSS
            .replace("GAUGE", &gauge.display().to_string())
            .replace("OTHER", &root.display().to_string());
        std::fs::write(opi.join(LAUNCHER), script).unwrap();
        for f in [
            opi.join("x.opi"),
            opi.join("common/c.opi"),
            gauge.join("g.opi"),
        ] {
            std::fs::write(f, "<display/>").unwrap();
        }
        (root, opi, gauge)
    }

    #[test]
    fn a_launcher_is_a_project() {
        let (root, opi, gauge) = module("runcss", Some("1-2"));
        let proj = opi.join("runcss.sh/vac_1-2");
        let x = proj.join("vac/x.opi");
        assert_eq!(launcher_path(&opi.join("x.opi")), Some(x.clone()));
        assert_eq!(
            launcher_path(&opi.join("common/c.opi")),
            Some(proj.join("vac/common/c.opi"))
        );
        assert_eq!(launcher_path(&gauge.join("g.opi")), None);
        assert_eq!(launcher_path(&x), None);
        // Links between the modules resolve through the virtual project.
        assert_eq!(locate(&x), opi.join("x.opi"));
        assert_eq!(
            locate(&proj.join("vac/../gauge/g.opi")),
            gauge.join("g.opi")
        );
        assert_eq!(locate(&proj.join("vac/common/../x.opi")), opi.join("x.opi"));
        // Only links of this project with a usable name and real folder.
        let names: Vec<String> = links(&proj).unwrap().into_iter().map(|l| l.0).collect();
        assert_eq!(names, ["vac", "gauge"]);
        assert_eq!(
            links(&opi.join("runcss.sh/elsewhere")).unwrap()[0],
            ("other".to_string(), root.clone())
        );
        assert_eq!(links(&opi.join("runcss.sh/vac_dev")), None);
        // `-p` takes the module's folder or its launcher.
        assert_eq!(project_dir(&opi), Some(proj.clone()));
        assert_eq!(project_dir(&opi.join(LAUNCHER)), Some(proj.clone()));
        assert_eq!(project_dir(&gauge), None);
        assert_eq!(
            virtual_path(&proj, &gauge.join("g.opi")),
            Some(proj.join("gauge/g.opi"))
        );
        std::fs::remove_dir_all(&root).unwrap();
    }

    #[cfg(unix)]
    #[test]
    fn reads_a_generated_launcher() {
        // vacuum 4-100's, verbatim.
        let text = include_str!("testdata/runcss.sh");
        let dir = Path::new("/nowhere/vacuum/4-100/vacuumApp/opi/opi");
        let projects = parse_launcher(text, dir);
        let [(project, links)] = projects.as_slice() else {
            panic!("{projects:?}")
        };
        assert_eq!(project, "vacuum_dev");
        assert_eq!(links.len(), 14);
        assert_eq!(links[0], ("vacuum".to_string(), dir.to_path_buf()));
        let support = Path::new("/dls_sw/prod/R3.14.12.7/support");
        assert_eq!(
            links[2],
            (
                "mks937a".to_string(),
                support.join("mks937a/2-90/mks937aApp/opi/opi")
            )
        );
        assert_eq!(links[13].0, "devIocStats");
    }

    #[cfg(unix)]
    #[test]
    fn reads_a_launcher_that_sources_versions_and_calls_functions() {
        // diagOpi 2-90's, verbatim: its links come from `opi-versions`,
        // functions, `join` and `configure-ioc`.
        let top = tmp("diag-runcss");
        std::fs::create_dir_all(top.join("configure")).unwrap();
        std::fs::write(top.join("configure/VERSION"), "2-90\n").unwrap();
        std::fs::write(
            top.join("opi-versions"),
            include_str!("testdata/diag-opi-versions"),
        )
        .unwrap();
        let table = top.join("redirect_table");
        std::fs::write(
            &table,
            "CSS-gui /x/css.sh\nDI-EBPM-gui-dir /ioc/Libera/2-05-17\nDI-MBF-gui-dir /ioc/MBF/1\n",
        )
        .unwrap();
        let text = include_str!("testdata/diag-runcss.sh");
        let projects = parse_launcher_with(text, &top, &table);
        let [(project, links)] = projects.as_slice() else {
            panic!("{projects:?}")
        };
        assert_eq!(project, "diagOpi_2-90");
        let support = Path::new("/dls_sw/prod/R3.14.12.3/support");
        let names: Vec<&str> = links.iter().map(|l| l.0.as_str()).collect();
        assert_eq!(
            names,
            [
                "diagOpi",
                "motor",
                "devIocStats",
                "enzLoCuM4",
                "pmacUtil",
                "TimingTemplates",
                "4chTimer",
                "dlsPLC",
                "Libera",
                "IsaPBPM",
                "MBF",
            ]
        );
        assert_eq!(links[0].1, normalize(&top));
        assert_eq!(
            links[2].1,
            support.join("devIocStats/3-1-14dls2-0/devIocStatsApp/opi/opi")
        );
        assert_eq!(links[8].1, Path::new("/ioc/Libera/2-05-17/opi"));
        // As in the shell, a name not in the table leaves its variable empty.
        assert_eq!(links[9].1, Path::new("/opi"));
        assert_eq!(links[10].1, Path::new("/ioc/MBF/1/opi"));
        std::fs::remove_dir_all(&top).unwrap();
    }

    #[test]
    fn only_boy_screens_go_through_a_launcher() {
        let (root, opi, _) = module("runcss-bob", Some("1-2"));
        let boy = r#"<display typeId="org.csstudio.opibuilder.Display" version="1.0.0"/>"#;
        std::fs::write(opi.join("x.opi"), boy).unwrap();
        std::fs::write(opi.join("y.bob"), r#"<display version="2.0.0"/>"#).unwrap();
        let source = |p: &Path| crate::Display::load(p).unwrap().source;
        let x = opi.join("runcss.sh/vac_1-2/vac/x.opi");
        assert_eq!(source(&opi.join("x.opi")), Some(crate::Source::File(x)));
        let y = opi.join("y.bob");
        assert_eq!(source(&y), Some(crate::Source::File(y.clone())));
        // Nor does a `.bob` reached through the launcher's project: it goes
        // by its real path, so its `..` names its real neighbours.
        std::fs::create_dir_all(opi.join("sub")).unwrap();
        let z = opi.join("sub/z.bob");
        std::fs::write(&z, r#"<display version="2.0.0"/>"#).unwrap();
        let d = crate::Display::load(&opi.join("runcss.sh/vac_1-2/vac/sub/z.bob")).unwrap();
        assert_eq!(d.source, Some(crate::Source::File(z)));
        let crate::Source::File(up) = d.resolve("../y.bob") else {
            panic!("not a file")
        };
        assert_eq!(normalize(&up), y);
        assert!(up.exists());
        std::fs::remove_dir_all(&root).unwrap();
    }

    #[cfg(unix)]
    #[test]
    fn symlinked_screens_map_by_name_or_by_target() {
        let (root, opi, _) = module("runcss-links", Some("1-2"));
        let proj = opi.join("runcss.sh/vac_1-2");
        // In a linked folder, a link keeps its own name.
        std::os::unix::fs::symlink("x.opi", opi.join("y.opi")).unwrap();
        assert_eq!(
            launcher_path(&opi.join("y.opi")),
            Some(proj.join("vac/y.opi"))
        );
        // Elsewhere, it goes by where it points.
        let home = root.join("home");
        std::fs::create_dir_all(&home).unwrap();
        std::os::unix::fs::symlink(opi.join("x.opi"), home.join("z.opi")).unwrap();
        assert_eq!(
            virtual_path(&proj, &home.join("z.opi")),
            Some(proj.join("vac/x.opi"))
        );
        std::fs::remove_dir_all(&root).unwrap();
    }

    #[test]
    fn a_project_file_beside_a_launcher_wins_only_with_links() {
        let (root, opi, gauge) = module("runcss-empty", Some("1-2"));
        let proj = opi.join("runcss.sh/vac_1-2");
        // An empty one, as DLS modules often have.
        std::fs::write(opi.join(".project"), "<projectDescription/>").unwrap();
        assert_eq!(
            launcher_path(&opi.join("x.opi")),
            Some(proj.join("vac/x.opi"))
        );
        assert_eq!(project_dir(&opi), Some(proj));
        // One linking the file wins.
        let linking = format!(
            "<projectDescription><linkedResources>
            <link><name>me</name><location>{}</location></link>
            </linkedResources></projectDescription>",
            opi.display()
        );
        std::fs::write(opi.join(".project"), linking).unwrap();
        forget();
        assert_eq!(launcher_path(&opi.join("x.opi")), None);
        assert_eq!(project_dir(&opi), Some(opi.clone()));
        // An empty `.project` and no launcher is still a project.
        std::fs::write(gauge.join(".project"), "<projectDescription/>").unwrap();
        assert_eq!(project_dir(&gauge), Some(gauge.clone()));
        std::fs::remove_dir_all(&root).unwrap();
    }

    #[test]
    fn the_launcher_is_near_the_screen() {
        let (root, opi, _) = module("runcss-deep", Some("1-2"));
        let deep = opi.join("a/b/c");
        std::fs::create_dir_all(&deep).unwrap();
        std::fs::write(deep.join("d.opi"), "<display/>").unwrap();
        std::fs::write(opi.join("a/b/e.opi"), "<display/>").unwrap();
        assert_eq!(launcher_path(&deep.join("d.opi")), None);
        assert_eq!(
            launcher_path(&opi.join("a/b/e.opi")),
            Some(opi.join("runcss.sh/vac_1-2/vac/a/b/e.opi"))
        );
        std::fs::remove_dir_all(&root).unwrap();
    }

    #[test]
    fn forget_reads_launchers_again() {
        let (root, opi, _) = module("runcss-forget", Some("1-2"));
        assert!(project_dir(&opi).is_some());
        let text = std::fs::read_to_string(opi.join(LAUNCHER)).unwrap();
        std::fs::write(
            opi.join(LAUNCHER),
            text.replace("project=vac_", "project=new_"),
        )
        .unwrap();
        // (Not checked before `forget`: other tests forget too.)
        forget();
        assert_eq!(project_dir(&opi), Some(opi.join("runcss.sh/new_1-2")));
        std::fs::remove_dir_all(&root).unwrap();
    }

    #[test]
    fn a_launcher_without_a_version_is_dev() {
        let (root, opi, _) = module("runcss-dev", None);
        assert_eq!(
            launcher_path(&opi.join("x.opi")),
            Some(opi.join("runcss.sh/vac_dev/vac/x.opi"))
        );
        std::fs::remove_dir_all(&root).unwrap();
    }

    #[test]
    fn a_nearer_project_file_wins_over_a_launcher() {
        let (root, opi, _) = module("runcss-project", Some("1-2"));
        let common = opi.join("common");
        // Only if it links the screen.
        std::fs::write(common.join(".project"), "<projectDescription/>").unwrap();
        assert!(launcher_path(&common.join("c.opi")).is_some());
        let linking = format!(
            "<projectDescription><linkedResources>
            <link><name>me</name><location>{}</location></link>
            </linkedResources></projectDescription>",
            common.display()
        );
        std::fs::write(common.join(".project"), linking).unwrap();
        forget();
        assert_eq!(launcher_path(&common.join("c.opi")), None);
        // One further away than the launcher does not.
        std::fs::write(root.join(".project"), "<projectDescription/>").unwrap();
        assert!(launcher_path(&opi.join("x.opi")).is_some());
        std::fs::remove_dir_all(&root).unwrap();
    }

    #[cfg(unix)]
    #[test]
    fn a_function_calling_itself_ends() {
        let text = "f()\n{\n    echo \"$(f)\"\n}\nx=$(f)\nlinks=\"/a=/p/n\"\n";
        let projects = parse_launcher_with(text, Path::new("/nowhere"), Path::new("/no/table"));
        assert_eq!(projects.len(), 1);
    }

    #[test]
    fn expands_shell_variables() {
        let shell = Shell {
            vars: HashMap::from([("a".to_string(), "1".to_string())]),
            functions: HashMap::new(),
            table: PathBuf::new(),
        };
        let e = |t: &str| shell.expand(t).unwrap();
        assert_eq!(e("x${a}y$a/$b.$"), "x1y1/.$");
        assert_eq!(e("${a"), "${a");
    }

    #[test]
    fn normalizes_lexically() {
        assert_eq!(
            normalize(Path::new("/a/b/../c/./d")),
            PathBuf::from("/a/c/d")
        );
        assert_eq!(normalize(Path::new("../x")), PathBuf::from("../x"));
        assert_eq!(normalize(Path::new("../../x")), PathBuf::from("../../x"));
        assert_eq!(normalize(Path::new("a/../../x")), PathBuf::from("../x"));
        assert_eq!(normalize(Path::new("/../x")), PathBuf::from("/x"));
    }

    #[test]
    fn oversized_project_files_are_ignored_not_cached_empty() {
        let dir = std::env::temp_dir().join(format!("bobview-bigproj-{}", std::process::id()));
        std::fs::create_dir_all(&dir).unwrap();
        let link = format!(
            "<link><name>a</name><location>{}</location></link>",
            std::env::temp_dir().display()
        );
        let pad = " ".repeat(MAX_PROJECT_SIZE as usize);
        std::fs::write(dir.join(".project"), format!("<p>{pad}{link}</p>")).unwrap();
        assert!(links(&dir).is_none());
        std::fs::write(dir.join(".project"), format!("<p>{link}</p>")).unwrap();
        assert_eq!(links(&dir).map(|l| l.len()), Some(1));
        std::fs::remove_dir_all(&dir).ok();
    }
}