forbidden-strings 0.3.0

//! Rule compiler targeting the in-house `forbidden-regex` engine.
//!
//! This module owns the two-form rule-file format, the flag policy, UTF-8 BOM
//! stripping, redacted load-error reporting, and both construction paths (from
//! rule text and from a serialized precompiled `RegexSet`). It is the live load
//! path: `crate::frx_load` builds the scan's rule sets through these entry points,
//! and `crate::frx_scan` runs them. The resharp/`regex`-crate pipeline it once sat
//! beside was deleted in the engine-swap teardown (#385).
//!
//! The engine is always in verbose, multiline mode, so this compiler never calls
//! `forbidden_regex::compile` (its single-pattern path logs the pattern via
//! `tracing`, a leak vector). It builds only through `RegexSet::new` and
//! `RegexSet::from_bytes`, neither of which logs, so a failing rule's bytes never
//! reach a subscriber.

/// Imports the engine's compiled-ruleset type and its compile-time error.
use forbidden_regex::{CompileError, RegexSet};

/// Registers the redacted load-error type.
mod error;
/// Registers the literal-to-verbose-dialect escaper.
mod escape;
/// Registers the format autodetector, legacy line parser, and flag policy.
mod format;
/// Registers the tail-format sectioned parser and header grammar.
mod sections;

/// Re-exports the redacted load-error type as this module's public failure.
pub use error::LoadError;

/// Re-exports the literal-to-verbose-dialect escaper for the scanner's fuzz targets.
///
/// The `fuzz_literal_roundtrip` target drives this escaper directly (not through the
/// two-form format layer, whose `.trim()`, comment, and regex classification would
/// eat the adversarial cases it must exercise: leading `#`, embedded newlines, a
/// leading `/`). Gated on `fuzzing` so the production surface stays unchanged.
#[cfg(feature = "fuzzing")]
pub use escape::escape_literal;

/// One compiled rule set paired with the per-rule names that drive finding identity.
///
/// `names` is parallel to the set's rule indices: a tail-format source names every
/// rule (its section name, rendered in findings as `rule=<name>`), a legacy source
/// names none (findings fall back to the offset numeric index). Splitting the two
/// out of the parse keeps the engine set free of identity concerns.
pub struct CompiledRules {
    /// Compiled engine set the scan path runs.
    pub set: RegexSet,
    /// Per-rule section names parallel to the set's rule indices; `None` for
    /// legacy line-based rules.
    pub names: Vec<Option<String>>,
}

/// Compiles a rule source into a combined `RegexSet` plus its per-rule names.
///
/// Parses the autodetected format (escaping literals, applying the flag policy,
/// stripping a BOM), then validates each rule through the engine to attribute a
/// redacted, index-bearing error to the first offender, and finally assembles the
/// combined set. Validation and assembly both go through `RegexSet::new`, so no
/// pattern is ever logged. Errors carry only an opaque rule index and the
/// engine's static reason, never rule text.
pub fn compile_rules(text: &str) -> Result<CompiledRules, LoadError> {
    let rules = format::parse_rules(text)?;
    let (names, patterns): (Vec<Option<String>>, Vec<String>) =
        rules.into_iter().map(|rule| return (rule.name, rule.pattern)).unzip();
    // Validate rule by rule first: `RegexSet::new` over the whole slice reports
    // only its first error without the offending index, so a per-rule pass
    // recovers the index for the redacted diagnostic. Each single-rule set is
    // discarded; the combined set is built once below.
    for (index, pattern) in patterns.iter().enumerate() {
        if let Err(reason) = RegexSet::new(std::slice::from_ref(pattern)) {
            return Err(LoadError::Compile { index, reason });
        }
    }
    // Every rule compiled individually, so assembly cannot fail on a rule; any
    // error here is a genuine engine invariant break, surfaced fail-closed with a
    // sentinel index and the engine's static reason (still no rule text).
    let set = RegexSet::new(&patterns).map_err(|reason| return LoadError::Compile {
        index: patterns.len(),
        reason,
    })?;
    return Ok(CompiledRules { set, names });
}

/// Compiles a rule source (autodetected format) into a combined `RegexSet`.
///
/// A projection over [`compile_rules`] for callers that only need the engine set
/// (the build-time baseline verifier, the fuzz targets); the runtime loader uses
/// [`compile_rules`] so findings can carry rule names.
pub fn compile_from_text(text: &str) -> Result<RegexSet, LoadError> {
    return compile_rules(text).map(|compiled| return compiled.set);
}

/// Loads a precompiled serialized `RegexSet` from bytes.
///
/// Wraps the engine's `from_bytes`, which decodes and structurally validates the
/// blob before it can match. The planning doc resolved that the builtin baseline
/// is embedded precompiled at build time (runtime compilation is too slow); stage
/// two performs the embedding, and this is the construction path it will use. A
/// decode or validation failure becomes a redacted `Precompiled` error.
pub fn load_precompiled(bytes: &[u8]) -> Result<RegexSet, LoadError> {
    return RegexSet::from_bytes(bytes)
        .map_err(|reason: CompileError| return LoadError::Precompiled { reason });
}

/// Registers the compile, redaction, and precompiled round-trip tests
/// (sidecar, lint-exempt).
#[cfg(test)]
mod compile_tests;