fallow-core 3.45.0

Internal detector backend for fallow-engine and fallow-api
Documentation
//! Read one `{ find, replacement }` alias entry.
//!
//! Vite and Rollup accept a string or a regular expression as `find`. The
//! resolver keeps aliases as `(prefix, replacement)` pairs, so only three regex
//! shapes map to it:
//! - An anchored literal, such as `/^node:module$/`. The key is the literal.
//! - An anchored prefix with one trailing capture, such as `/^@\/(.*)$/`, when
//!   the replacement ends with `/$1`. The key is the prefix and the replacement
//!   loses the `/$1` suffix.
//! - An anchored prefix that ends with a slash, such as `/^@\//`, when the
//!   replacement ends with a slash. The key keeps the slash.
//!
//! Every other regex gives no alias.
//!
//! Limit: the resolver matches every key as a prefix. Thus an exact key such as
//! `lodash` from `/^lodash$/` also matches `lodash/fp`, which Vite does not
//! alias. A capture key also matches `<prefix>` without a rest.

use std::path::Path;

use oxc_ast::ast::{
    ArrayExpressionElement, Expression, ObjectExpression, Program, RegExpFlags, RegExpLiteral,
    TemplateLiteral,
};

use super::{
    MAX_ALIAS_RESOLVE_DEPTH, PathScope, alias_replacement_kinded, expression_to_string,
    extract_from_source, find_property, find_variable_init_expression, get_nested_expression,
    is_package_specifier, path_string_in, read_each_config,
};

/// The capture group text that matches the rest of the specifier.
const REST_CAPTURES: &[&str] = &["(.*)", "(.+)"];

/// The replacement suffix that inserts the first capture after a slash.
const CAPTURE_SUFFIX: &str = "/$1";

/// The key that a regex `find` maps to.
#[derive(Debug, PartialEq, Eq)]
enum RegexAliasKey {
    /// The regex matches one specifier only.
    Exact(String),
    /// The regex matches `<prefix>/<rest>` and captures `<rest>` as `$1`.
    Prefix(String),
    /// The regex matches a leading `<prefix>/` and does not capture the rest.
    /// The key keeps the trailing slash.
    SlashPrefix(String),
}

/// Build the `(find, replacement, is_bare)` tuple of one alias array entry.
///
/// A string `find` is the alias key as written. A regular expression `find`
/// maps to a key only when the prefix alias model can express it; see
/// [`regex_alias_pair`].
pub(super) fn object_alias_pair(
    obj: &ObjectExpression<'_>,
    scope: PathScope<'_>,
) -> Option<(String, String, bool)> {
    let find = &find_property(obj, "find")?.value;
    let (replacement, is_bare) = find_property(obj, "replacement")
        .and_then(|prop| alias_replacement_kinded(&prop.value, scope))?;
    match find.without_parentheses() {
        Expression::RegExpLiteral(regex) => regex_alias_pair(regex, &replacement)
            .map(|(key, replacement)| (key, replacement, is_bare)),
        other => expression_to_string(other).map(|key| (key, replacement, is_bare)),
    }
}

/// Extract the packages that alias entries with a regular expression `find`
/// name as their replacement, such as `identity-obj-proxy` in
/// `{ find: /\.css$/, replacement: 'identity-obj-proxy' }`.
///
/// The prefix alias model can not express most of these entries, but Vite
/// still loads the replacement package. The walk follows array spreads and
/// local bindings. It does not read imported alias modules.
#[must_use]
pub fn extract_config_regex_alias_packages(
    source: &str,
    path: &Path,
    prop_path: &[&str],
) -> Vec<String> {
    extract_from_source(source, path, |program| {
        read_each_config(program, |obj| {
            let expr = get_nested_expression(obj, prop_path)?;
            let mut packages = Vec::new();
            regex_alias_packages(program, expr, 0, &mut packages);
            (!packages.is_empty()).then_some(packages)
        })
    })
    .unwrap_or_default()
}

fn regex_alias_packages(
    program: &Program<'_>,
    expr: &Expression<'_>,
    depth: usize,
    packages: &mut Vec<String>,
) {
    if depth >= MAX_ALIAS_RESOLVE_DEPTH {
        return;
    }
    match expr.get_inner_expression() {
        Expression::ArrayExpression(arr) => {
            for element in &arr.elements {
                match element {
                    ArrayExpressionElement::SpreadElement(spread) => {
                        regex_alias_packages(program, &spread.argument, depth + 1, packages);
                    }
                    _ => {
                        if let Some(Expression::ObjectExpression(obj)) = element.as_expression()
                            && let Some(package) =
                                regex_find_package(obj, PathScope::Program(program))
                        {
                            packages.push(package);
                        }
                    }
                }
            }
        }
        Expression::Identifier(id) => {
            if let Some(init) = find_variable_init_expression(program, id.name.as_str()) {
                regex_alias_packages(program, init, depth + 1, packages);
            }
        }
        _ => {}
    }
}

/// The package that one `{ find, replacement }` entry names, when `find` is a
/// regular expression and `replacement` is a bare package string. A `$`
/// reference in the package name gives no package, because the capture
/// decides the name.
fn regex_find_package(obj: &ObjectExpression<'_>, scope: PathScope<'_>) -> Option<String> {
    let find = &find_property(obj, "find")?.value;
    if !matches!(find.without_parentheses(), Expression::RegExpLiteral(_)) {
        return None;
    }
    let (replacement, is_bare) = find_property(obj, "replacement")
        .and_then(|prop| alias_replacement_kinded(&prop.value, scope))?;
    if !is_bare || !is_package_specifier(&replacement) {
        return None;
    }
    let package = crate::resolve::extract_package_name(&replacement);
    (!package.contains('$')).then_some(package)
}

/// Evaluate an alias replacement path. A template literal that starts with a
/// path call, such as `${path.resolve(__dirname, 'src')}/$1`, is read too,
/// because regex aliases use it to append a capture reference to a directory.
pub(super) fn path_value(expr: &Expression<'_>, scope: PathScope<'_>) -> Option<String> {
    match expr {
        Expression::TemplateLiteral(template) if !template.expressions.is_empty() => {
            path_template_string(template, scope)
        }
        _ => path_string_in(expr, scope),
    }
}

/// Concatenate a template literal whose interpolations all evaluate to paths.
/// An unknown identifier, such as `${dirname}`, gives no value.
fn path_template_string(template: &TemplateLiteral<'_>, scope: PathScope<'_>) -> Option<String> {
    let starts_with_path_call = template.quasis.first()?.value.raw.is_empty()
        && matches!(
            template.expressions.first()?.without_parentheses(),
            Expression::CallExpression(_) | Expression::NewExpression(_)
        );
    if !starts_with_path_call {
        return None;
    }
    let mut value = String::new();
    for (index, quasi) in template.quasis.iter().enumerate() {
        value.push_str(quasi.value.raw.as_str());
        if let Some(expr) = template.expressions.get(index) {
            value.push_str(&path_string_in(expr, scope)?);
        }
    }
    Some(value)
}

/// Convert a regex `find` and its evaluated replacement to an alias pair.
///
/// Returns `None` when the regex has a shape that the prefix model can not
/// express. A replacement that keeps a `$` reference after the conversion is
/// also refused, because the resolver substitutes no capture groups.
fn regex_alias_pair(regex: &RegExpLiteral<'_>, replacement: &str) -> Option<(String, String)> {
    if !regex
        .regex
        .flags
        .difference(RegExpFlags::U | RegExpFlags::V)
        .is_empty()
    {
        return None;
    }
    let key = parse_regex_alias_key(regex.regex.pattern.text.as_str())?;
    alias_pair_for_key(key, replacement)
}

/// Pair a parsed regex key with its replacement.
///
/// A slash prefix key needs a replacement that ends with a slash. Vite replaces
/// only the matched text, so `#/b` with `/^#\//` and `/src/lib` gives
/// `/src/libb`, which the prefix model can not express.
fn alias_pair_for_key(key: RegexAliasKey, replacement: &str) -> Option<(String, String)> {
    let (key, replacement) = match key {
        RegexAliasKey::Exact(key) => (key, replacement),
        RegexAliasKey::Prefix(key) => (key, replacement.strip_suffix(CAPTURE_SUFFIX)?),
        RegexAliasKey::SlashPrefix(key) => {
            replacement.strip_suffix('/')?;
            (key, replacement)
        }
    };
    if replacement.contains('$') {
        return None;
    }
    Some((key, replacement.to_owned()))
}

/// Parse the pattern text of a regex `find` into an alias key.
fn parse_regex_alias_key(pattern: &str) -> Option<RegexAliasKey> {
    let body = pattern.strip_prefix('^')?;
    for capture in REST_CAPTURES {
        let Some(head) = body.strip_suffix('$').unwrap_or(body).strip_suffix(capture) else {
            continue;
        };
        let prefix = unescape_literal(head)?;
        let prefix = prefix.strip_suffix('/')?;
        return (!prefix.is_empty()).then(|| RegexAliasKey::Prefix(prefix.to_owned()));
    }
    if let Some(exact) = body.strip_suffix('$') {
        let literal = unescape_literal(exact)?;
        return (!literal.is_empty()).then_some(RegexAliasKey::Exact(literal));
    }
    let literal = unescape_literal(body)?;
    let has_name = literal
        .strip_suffix('/')
        .is_some_and(|name| !name.is_empty());
    has_name.then_some(RegexAliasKey::SlashPrefix(literal))
}

/// Read a regex fragment as literal text. Returns `None` when the fragment has
/// a metacharacter or an escape that is not a plain punctuation character.
fn unescape_literal(fragment: &str) -> Option<String> {
    let mut literal = String::with_capacity(fragment.len());
    let mut chars = fragment.chars();
    while let Some(ch) = chars.next() {
        match ch {
            '\\' => {
                let escaped = chars.next()?;
                if escaped.is_ascii_alphanumeric() {
                    return None;
                }
                literal.push(escaped);
            }
            '.' | '*' | '+' | '?' | '(' | ')' | '[' | ']' | '{' | '}' | '|' | '^' | '$' => {
                return None;
            }
            _ => literal.push(ch),
        }
    }
    Some(literal)
}

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

    #[test]
    fn anchored_literal_maps_to_an_exact_key() {
        assert_eq!(
            parse_regex_alias_key("^node:module$"),
            Some(RegexAliasKey::Exact("node:module".to_owned()))
        );
        assert_eq!(
            parse_regex_alias_key(r"^@scope\/pkg$"),
            Some(RegexAliasKey::Exact("@scope/pkg".to_owned()))
        );
        assert_eq!(
            parse_regex_alias_key(r"^lodash\.debounce$"),
            Some(RegexAliasKey::Exact("lodash.debounce".to_owned()))
        );
    }

    #[test]
    fn anchored_capture_maps_to_a_prefix_key() {
        for pattern in [r"^@\/(.*)$", "^@/(.*)$", r"^@\/(.+)$", r"^@\/(.*)"] {
            assert_eq!(
                parse_regex_alias_key(pattern),
                Some(RegexAliasKey::Prefix("@".to_owned())),
                "{pattern}"
            );
        }
        assert_eq!(
            parse_regex_alias_key(r"^~lib\/(.*)$"),
            Some(RegexAliasKey::Prefix("~lib".to_owned()))
        );
    }

    #[test]
    fn anchored_slash_prefix_maps_to_a_slash_prefix_key() {
        for (pattern, key) in [(r"^@\/", "@/"), (r"^#\/", "#/"), ("^~lib/", "~lib/")] {
            assert_eq!(
                parse_regex_alias_key(pattern),
                Some(RegexAliasKey::SlashPrefix(key.to_owned())),
                "{pattern}"
            );
        }
    }

    #[test]
    fn slash_prefix_needs_a_replacement_that_ends_with_a_slash() {
        let pair = |pattern: &str, replacement: &str| {
            let key = parse_regex_alias_key(pattern)?;
            alias_pair_for_key(key, replacement)
        };
        assert_eq!(
            pair(r"^#\/", "/src/lib/"),
            Some(("#/".to_owned(), "/src/lib/".to_owned()))
        );
        assert_eq!(pair(r"^#\/", "/src/lib"), None);
    }

    #[test]
    fn other_regex_shapes_give_no_key() {
        for pattern in [
            "node:module",
            "^lodash",
            r"\.svg$",
            "^lodash.debounce$",
            r"^(foo|bar)$",
            r"^@(.*)$",
            r"^\/(.*)$",
            r"^@\/(.*)\.js$",
            r"^\d+$",
            "^$",
            r"^\/",
            r"^@\/.*",
        ] {
            assert_eq!(parse_regex_alias_key(pattern), None, "{pattern}");
        }
    }
}