cuke-dedup 0.11.0

//! Shared intermediate representation and diagnostics.

mod behavior;
mod handler;
pub(crate) use handler::{bounded_source_snippet, HandlerSemantics};
mod sha256;

pub(crate) use behavior::{BehaviorEvent, BehaviorEventRef, ControlFlowOperation};

use serde::{Deserialize, Serialize};
use std::collections::{BTreeSet, HashSet};
use std::fmt;
use std::path::{Path, PathBuf};
use std::str::FromStr;

use self::sha256::Sha256;

#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
/// Source span with one-based starts and one-based, exclusive end coordinates.
pub struct SourceLocation {
    /// Absolute or caller-provided source path.
    pub path: PathBuf,
    /// One-based start line.
    pub line: usize,
    /// One-based start column.
    pub column: usize,
    /// One-based line containing the exclusive end position.
    pub end_line: usize,
    /// One-based, exclusive end column in the original source text.
    pub end_column: usize,
}

impl SourceLocation {
    /// Creates a source location from a path and one-based span coordinates.
    pub fn new(
        path: impl Into<PathBuf>,
        line: usize,
        column: usize,
        end_line: usize,
        end_column: usize,
    ) -> Self {
        Self {
            path: path.into(),
            line,
            column,
            end_line,
            end_column,
        }
    }

    /// Formats the location as `path:line:column`, relative to `root` when possible.
    pub fn display(&self, root: &Path) -> String {
        let path = self.path.strip_prefix(root).unwrap_or(&self.path);
        let path = path.to_string_lossy().replace('\\', "/");
        format!("{path}:{}:{}", self.line, self.column)
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
/// Syntax used by a step definition matcher.
#[non_exhaustive]
pub enum MatcherKind {
    /// Literal text in a positional Jest-Cucumber step, without expression placeholders.
    Literal,
    /// A Cucumber Expression such as `I have {int} items`.
    CucumberExpression,
    /// A JavaScript regular expression.
    RegularExpression,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
/// Step-definition framework inferred from a source file.
#[non_exhaustive]
pub enum Framework {
    /// Direct Cucumber-Ruby block registrations.
    CucumberRuby,
    /// Cucumber.js registration APIs.
    CucumberJs,
    /// Playwright BDD registration APIs.
    PlaywrightBdd,
    /// Cypress step definitions registered through the Badeball Cucumber preprocessor.
    CypressCucumber,
    /// Jest-Cucumber's positional, scenario-local step callbacks.
    JestCucumber,
    /// Global registrations exported by vitest-cucumber-plugin.
    VitestCucumber,
    /// No supported framework import could be inferred.
    Unknown,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
/// Comparable representations of a definition handler.
pub struct HandlerFingerprint {
    /// Exact syntax-tree representation.
    pub exact: String,
    /// Representation normalized for superficial syntax differences.
    pub normalized: String,
    /// Representation with parameter and local identifiers normalized.
    pub alpha_normalized: String,
    /// Control-flow and call structure with literals normalized.
    pub structural: String,
    /// Ordered behavioral operations observed in the handler.
    pub behavior_signature: Vec<String>,
    /// Bounded original source displayed in reports.
    pub source_snippet: String,
    /// Whether a concrete handler body was available for comparison.
    #[serde(default)]
    pub comparable: bool,
    #[serde(default)]
    /// Whether the handler lacks enough behavior for duplication analysis.
    pub trivial: bool,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
/// Rule-scoped, reason-bearing suppression declared beside a definition.
pub struct InlineSuppression {
    /// Rule disabled for findings involving this definition.
    pub rule: Rule,
    /// Human-readable justification retained in reports.
    pub reason: String,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
/// A step definition extracted into the analyzer's shared representation.
pub struct StepDefinition {
    /// Original matcher text without language-specific delimiters.
    pub matcher: String,
    /// Canonical matcher used for equivalence checks.
    pub normalized_matcher: String,
    /// Matcher syntax.
    pub matcher_kind: MatcherKind,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    /// Source-language regular-expression flags, or an empty string otherwise.
    pub matcher_flags: String,
    /// Comparable handler representations.
    pub handler: HandlerFingerprint,
    /// Framework that registered the definition.
    pub framework: Framework,
    /// Registration name resolved from direct, aliased, or namespaced usage.
    pub registration: String,
    /// Full registration call location.
    pub location: SourceLocation,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    /// Source-local suppression directives attached to this definition.
    pub inline_suppressions: Vec<InlineSuppression>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
/// One concrete step from a parsed Gherkin scenario.
pub struct FeatureStep {
    /// Localized Gherkin keyword.
    pub keyword: String,
    /// Concrete step text after Scenario Outline expansion.
    pub text: String,
    /// Source location of the originating step.
    pub location: SourceLocation,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
/// Stable identifier for an analyzer rule.
#[non_exhaustive]
pub enum Rule {
    /// Two definitions have the same effective matcher.
    DuplicateMatcher,
    /// Two matchers become equivalent after normalization.
    NormalizedMatcher,
    /// A concrete feature step matches multiple definitions.
    AmbiguousStep,
    /// Two matchers can accept the same step text, independent of the feature corpus.
    OverlappingMatcher,
    /// Distinct matchers share an equivalent implementation.
    DuplicateHandler,
    /// Similar wording and handler structure indicate likely duplication.
    NearDuplicateStep,
    /// Similar definitions may be replaceable by a parameterized step.
    ParameterizationCandidate,
    /// No discovered feature step uses a definition.
    UnusedDefinition,
}

impl Rule {
    const DOCUMENTATION_BASE_URL: &'static str =
        "https://github.com/figueiredoluiz/cuke-dedup/blob/main/docs/rules.md#";

    /// Every rule in deterministic report order.
    pub const ALL: &'static [Rule] = &[
        Rule::DuplicateMatcher,
        Rule::NormalizedMatcher,
        Rule::AmbiguousStep,
        Rule::OverlappingMatcher,
        Rule::DuplicateHandler,
        Rule::NearDuplicateStep,
        Rule::ParameterizationCandidate,
        Rule::UnusedDefinition,
    ];

    /// Rules whose active error findings contribute to the duplication threshold.
    pub const DUPLICATION_THRESHOLD: &'static [Rule] = &[
        Rule::DuplicateMatcher,
        Rule::NormalizedMatcher,
        Rule::DuplicateHandler,
        Rule::NearDuplicateStep,
        Rule::ParameterizationCandidate,
    ];

    /// Returns the stable kebab-case configuration and report name.
    pub fn as_str(self) -> &'static str {
        match self {
            Rule::DuplicateMatcher => "duplicate-matcher",
            Rule::NormalizedMatcher => "normalized-matcher",
            Rule::AmbiguousStep => "ambiguous-step",
            Rule::OverlappingMatcher => "overlapping-matcher",
            Rule::DuplicateHandler => "duplicate-handler",
            Rule::NearDuplicateStep => "near-duplicate-step",
            Rule::ParameterizationCandidate => "parameterization-candidate",
            Rule::UnusedDefinition => "unused-definition",
        }
    }

    /// Returns whether error findings from this rule contribute to the duplication threshold.
    pub fn contributes_to_duplication_threshold(self) -> bool {
        Self::DUPLICATION_THRESHOLD.contains(&self)
    }

    /// Returns the rule-specific documentation URL used by diagnostics integrations.
    pub fn documentation_url(self) -> String {
        format!("{}{}", Self::DOCUMENTATION_BASE_URL, self.as_str())
    }
}

impl fmt::Display for Rule {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}

impl FromStr for Rule {
    type Err = String;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        match value {
            "duplicate-matcher" => Ok(Self::DuplicateMatcher),
            "normalized-matcher" => Ok(Self::NormalizedMatcher),
            "ambiguous-step" => Ok(Self::AmbiguousStep),
            "overlapping-matcher" => Ok(Self::OverlappingMatcher),
            "duplicate-handler" => Ok(Self::DuplicateHandler),
            "near-duplicate-step" => Ok(Self::NearDuplicateStep),
            "parameterization-candidate" => Ok(Self::ParameterizationCandidate),
            "unused-definition" => Ok(Self::UnusedDefinition),
            _ => Err(format!("unknown rule `{value}`")),
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
/// Configured impact of a finding.
#[non_exhaustive]
pub enum Severity {
    /// Rule evaluation is disabled.
    Off,
    /// Finding is reported without causing exit code 1.
    Warning,
    /// Active finding causes exit code 1.
    Error,
}

impl fmt::Display for Severity {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Severity::Off => f.write_str("off"),
            Severity::Warning => f.write_str("warning"),
            Severity::Error => f.write_str("error"),
        }
    }
}

impl FromStr for Severity {
    type Err = String;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        match value {
            "off" => Ok(Severity::Off),
            "warn" | "warning" => Ok(Severity::Warning),
            "error" => Ok(Severity::Error),
            _ => Err(format!(
                "invalid severity `{value}` (expected off, warning, or error)"
            )),
        }
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
/// Human- and machine-readable evidence supporting a finding.
#[non_exhaustive]
pub struct FindingEvidence {
    /// Matcher similarity score from zero to one, when applicable.
    pub matcher_similarity: Option<f64>,
    /// Handler similarity score from zero to one, when applicable.
    pub handler_similarity: Option<f64>,
    /// Concise matcher comparison for terminal output.
    pub matcher_difference: String,
    /// Concise handler comparison for terminal output.
    pub handler_evidence: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// Structured definition comparison for rich reports.
    pub comparison: Option<DefinitionComparison>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// Connected definition group when a large set of pair findings is collapsed.
    pub cluster: Option<DefinitionCluster>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
/// Stable semantic identity and size information for a clustered finding.
#[non_exhaustive]
pub struct DefinitionCluster {
    /// Total number of definitions represented by the cluster.
    pub member_count: usize,
    /// Location-independent fingerprints for every definition in the cluster.
    ///
    /// Reporters may retain only a bounded prefix and set [`Self::members_truncated`].
    pub definition_fingerprints: Vec<String>,
    /// Number of pair findings represented by the single cluster finding.
    pub pair_findings_collapsed: usize,
    /// Whether a reporter omitted members from its serialized representation.
    pub members_truncated: bool,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
/// Side-by-side matcher and handler content for a pair finding.
#[non_exhaustive]
pub struct DefinitionComparison {
    /// Location-independent semantic fingerprint of the left definition.
    pub left_fingerprint: String,
    /// Location-independent semantic fingerprint of the right definition.
    pub right_fingerprint: String,
    /// Left definition's original matcher.
    pub left_matcher: String,
    /// Right definition's original matcher.
    pub right_matcher: String,
    /// Left definition's bounded handler source.
    pub left_handler: String,
    /// Right definition's bounded handler source.
    pub right_handler: String,
    /// Structured common and changed matcher segments.
    pub matcher_diff: MatcherDiff,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
/// Common and differing segments of two matcher strings.
#[non_exhaustive]
pub struct MatcherDiff {
    /// Shared matcher prefix.
    pub prefix: String,
    /// Segment unique to the left matcher.
    pub left_change: String,
    /// Segment unique to the right matcher.
    pub right_change: String,
    /// Shared matcher suffix.
    pub suffix: String,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
/// Reason that a finding is excluded from active totals.
#[non_exhaustive]
pub struct Suppression {
    /// Human-readable suppression justification.
    pub reason: String,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
/// One rule diagnostic produced by analysis.
#[non_exhaustive]
pub struct Finding {
    /// Rule that produced the finding.
    pub rule: Rule,
    /// Configured impact.
    pub severity: Severity,
    /// Human-readable diagnostic message.
    pub message: String,
    /// Main source span.
    pub primary: SourceLocation,
    /// Additional spans involved in the finding.
    pub related: Vec<SourceLocation>,
    /// Comparison data supporting the diagnostic.
    pub evidence: FindingEvidence,
    /// Recommended remediation.
    pub suggested_action: String,
    /// Suppression metadata, when excluded from active totals.
    pub suppression: Option<Suppression>,
}

impl Finding {
    /// Returns whether the finding contributes to output totals and exit status.
    pub fn is_active(&self) -> bool {
        self.severity != Severity::Off && self.suppression.is_none()
    }
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
/// Extracted inputs and deterministically ordered analyzer findings.
#[non_exhaustive]
pub struct AnalysisResult {
    /// Extracted definition corpus.
    pub definitions: Vec<StepDefinition>,
    /// Concrete feature-step corpus.
    pub feature_steps: Vec<FeatureStep>,
    /// Findings produced by configured rules.
    pub findings: Vec<Finding>,
}

impl AnalysisResult {
    /// Creates a result from extracted inputs and analyzer findings.
    pub fn new(
        definitions: Vec<StepDefinition>,
        feature_steps: Vec<FeatureStep>,
        findings: Vec<Finding>,
    ) -> Self {
        Self {
            definitions,
            feature_steps,
            findings,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
/// Result of applying a percentage-based tolerance to active duplication errors.
#[non_exhaustive]
pub struct DuplicationThreshold {
    /// Maximum duplicated-definition percentage allowed by configuration.
    pub threshold: f64,
    /// Unique definitions involved in active error-level duplication findings.
    pub duplicated_definitions: usize,
    /// Total number of definitions discovered for the analysis.
    pub total_definitions: usize,
    /// Unrounded duplicated-definition percentage.
    pub percentage: f64,
    /// Whether the percentage is less than or equal to the configured threshold.
    pub passed: bool,
    /// Rules whose error-level findings contribute to the numerator.
    pub rules: Vec<Rule>,
}

impl DuplicationThreshold {
    /// Calculates the duplication rate after suppressions and analysis modes are applied.
    pub fn from_result(result: &AnalysisResult, threshold: f64) -> Self {
        let definition_locations: HashSet<_> = result
            .definitions
            .iter()
            .map(|definition| definition.location.clone())
            .collect();
        let mut duplicated_locations = HashSet::new();
        let mut contributing_rules = BTreeSet::new();
        for finding in result.findings.iter().filter(|finding| {
            finding.is_active()
                && finding.severity == Severity::Error
                && finding.rule.contributes_to_duplication_threshold()
        }) {
            contributing_rules.insert(finding.rule);
            for location in std::iter::once(&finding.primary).chain(&finding.related) {
                if definition_locations.contains(location) {
                    duplicated_locations.insert(location.clone());
                }
            }
        }

        let total_definitions = result.definitions.len();
        let duplicated_definitions = result
            .definitions
            .iter()
            .filter(|definition| duplicated_locations.contains(&definition.location))
            .count();
        let percentage = if total_definitions == 0 {
            0.0
        } else {
            duplicated_definitions as f64 / total_definitions as f64 * 100.0
        };
        Self {
            threshold,
            duplicated_definitions,
            total_definitions,
            percentage,
            passed: threshold.is_finite() && percentage <= threshold,
            rules: contributing_rules.into_iter().collect(),
        }
    }
}

const SINGLE_FINGERPRINT_DOMAIN: &[u8] = b"cuke-dedup:fingerprint:v3:single\0";
const MULTIPART_FINGERPRINT_DOMAIN: &[u8] = b"cuke-dedup:fingerprint:v3:parts\0";

/// Computes the first 128 bits of a domain-separated SHA-256 digest for report and comparison data.
pub fn stable_fingerprint(value: &str) -> String {
    let mut hasher = Sha256::new();
    hasher.update(SINGLE_FINGERPRINT_DOMAIN);
    hasher.update(value.as_bytes());
    truncated_sha256(hasher)
}

pub(crate) fn stable_fingerprint_parts<'a>(parts: impl IntoIterator<Item = &'a str>) -> String {
    let mut hasher = Sha256::new();
    hasher.update(MULTIPART_FINGERPRINT_DOMAIN);
    for part in parts {
        let bytes = part.as_bytes();
        let length = u64::try_from(bytes.len()).expect("fingerprint part length fits in u64");
        hasher.update(&length.to_be_bytes());
        hasher.update(bytes);
    }
    truncated_sha256(hasher)
}

fn truncated_sha256(hasher: Sha256) -> String {
    const HEX: &[u8; 16] = b"0123456789abcdef";
    let mut fingerprint = String::with_capacity(32);
    for byte in &hasher.finalize()[..16] {
        fingerprint.push(HEX[usize::from(byte >> 4)] as char);
        fingerprint.push(HEX[usize::from(byte & 0x0f)] as char);
    }
    fingerprint
}

#[cfg(test)]
mod tests;