monochromatic-git-policy-cli 0.6.0

//! What: Decide whether source text imports a package or one of its subpaths.
//! Why: A development dependency is bundled, and so carries a bump, only when non-test
//!      source imports it. This is the incumbent's specifier scan (`source-imports.ts:59-264`):
//!      a quoted specifier equal to the name, or starting with the name and `/`, directly
//!      after `from`, `import`, `import(` or `require(`. Every character it inspects is
//!      ASCII, so scanning UTF-8 bytes decides exactly what scanning UTF-16 units decides.
//!
//! In TS you'd write (pseudocode):
//! ```ts
//! // importsPackage({ sourceText, packageName });
//! ```

/// What: Keywords that put a string literal directly after them in specifier position.
/// Why:  `import x from 'p'`, `export * from 'p'` and `import 'p'`.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// const SPECIFIER_KEYWORDS = ['from', 'import'];
/// ```
const SPECIFIER_KEYWORDS: &[&[u8]] = &[b"from", b"import"];

/// What: Callees whose first argument is a module specifier.
/// Why:  `import('p')` and `require('p')`.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// const SPECIFIER_CALLEES = ['import', 'require'];
/// ```
const SPECIFIER_CALLEES: &[&[u8]] = &[b"import", b"require"];

/// What: Whether a byte can continue a JavaScript identifier, for keyword boundaries.
/// Why:  `reimport 'p'` and `myrequire('p')` are not specifiers.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// const isIdentifierCharacter = (c: string) => /[A-Za-z0-9_$]/.test(c);
/// ```
fn is_identifier_byte(byte: u8) -> bool {
    return byte.is_ascii_alphanumeric() || byte == b'_' || byte == b'$';
}

/// What: The exclusive end of the text before `end` once trailing whitespace is dropped.
///       `.rposition(...)` finds the last match.
/// Why:  Whitespace, including line breaks, may separate a keyword from its literal.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// function skipWhitespaceBackwards({ text, end }): number;
/// ```
fn skip_whitespace_backwards(text: &[u8], end: usize) -> usize {
    return match text[..end].iter().rposition(is_not_whitespace_byte) {
        Some(index) => index + 1,
        None => 0,
    };
}

/// What: Whether one byte is something other than a space, tab, carriage return or line feed.
/// Why:  `rposition` takes this function by path where a closure would otherwise stand.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// const isNotWhitespaceByte = (byte: number) => ![0x20, 0x09, 0x0d, 0x0a].includes(byte);
/// ```
fn is_not_whitespace_byte(byte: &u8) -> bool {
    return !matches!(byte, b' ' | b'\t' | b'\r' | b'\n');
}

/// What: Whether one of the keywords ends exactly at `end`, with no identifier byte before
///       it. `.checked_sub` is subtraction that yields nothing instead of going below zero.
/// Why:  A keyword must be a whole word.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// function endsWithKeyword({ text, end, keywords }): boolean;
/// ```
fn ends_with_keyword(text: &[u8], end: usize, keywords: &[&[u8]]) -> bool {
    for keyword in keywords {
        let Some(start) = end.checked_sub(keyword.len()) else {
            continue;
        };
        let before: Option<&u8> = match start.checked_sub(1) {
            Some(index) => text.get(index),
            None => None,
        };
        let identifier_before: bool = match before {
            Some(byte) => is_identifier_byte(*byte),
            None => false,
        };
        // The first keyword that ends here settles it, as `any` stopped at the first match.
        if text[start..end] == **keyword && !identifier_before {
            return true;
        }
    }
    return false;
}

/// What: Whether the string literal opening at `quote_index` is in specifier position.
/// Why:  `const name = '@scope/b'` mentions a package without importing it.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// function isSpecifierPosition({ text, quoteIndex }): boolean;
/// ```
fn is_specifier_position(text: &[u8], quote_index: usize) -> bool {
    let token_end: usize = skip_whitespace_backwards(text, quote_index);
    if ends_with_keyword(text, token_end, SPECIFIER_KEYWORDS) {
        return true;
    }
    // `let Some(...) = ... else` handles a literal at the very start, which has no `(`.
    let Some(paren) = token_end.checked_sub(1) else {
        return false;
    };
    return text[paren] == b'('
        && ends_with_keyword(
            text,
            skip_whitespace_backwards(text, paren),
            SPECIFIER_CALLEES,
        );
}

/// What: Whether source text imports the package or one of its subpaths.
///       `.match_indices(...)` yields each non-overlapping occurrence from the left, the
///       same occurrences the incumbent's `indexOf` loop visits.
/// Why:  The character before an occurrence must open a quote, the one after must close it
///       or start a subpath, and the literal must be in specifier position.
/// Gotcha: For an empty name the incumbent's loop never advances and does not terminate;
///         here every position is an occurrence, so the stated rule applies to it too.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// function importsPackage({ sourceText, packageName }): boolean;
/// ```
pub fn imports_package(source_text: &str, package_name: &str) -> bool {
    let text: &[u8] = source_text.as_bytes();
    for (index, _) in source_text.match_indices(package_name) {
        let Some(quote_index) = index.checked_sub(1) else {
            continue;
        };
        let quote: u8 = text[quote_index];
        let following: Option<&u8> = text.get(index + package_name.len());
        // The first occurrence in specifier position settles it, as `any` stopped at the first match.
        if matches!(quote, b'\'' | b'"' | b'`')
            && (following == Some(&quote) || following == Some(&b'/'))
            && is_specifier_position(text, quote_index)
        {
            return true;
        }
    }
    return false;
}

/// Specifier detection, including every case of the incumbent's unit tests.
#[cfg(test)]
#[path = "dependent_version_imports_tests.rs"]
mod tests;