ferro-jtype 0.2.8

Type inference for Java class bytecode without JDK symbols
Documentation
use crate::{
    ClassName, Diagnostic, DynamicCallKind, GenericSignature, InferredType, MethodDescriptor,
    ReturnType, TypeDescriptor,
};

/// Type-inference results for one Java class file.
///
/// Diagnostics describe recoverable conditions observed while processing the
/// class. Inspect them when consuming inference from malformed, unsupported,
/// or intentionally obfuscated bytecode.
#[derive(Debug, Clone)]
pub struct ClassInference {
    class_name: ClassName,
    generic_signature: Option<GenericSignature>,
    methods: Vec<MethodInference>,
    diagnostics: Vec<Diagnostic>,
}

impl ClassInference {
    pub(crate) fn new(
        class_name: ClassName,
        generic_signature: Option<GenericSignature>,
        methods: Vec<MethodInference>,
        diagnostics: Vec<Diagnostic>,
    ) -> Self {
        Self {
            class_name,
            generic_signature,
            methods,
            diagnostics,
        }
    }

    /// Returns the JVM internal name of the analyzed class.
    #[must_use]
    pub const fn class_name(&self) -> &ClassName {
        &self.class_name
    }

    /// Returns the class's generic `Signature` attribute, when present.
    #[must_use]
    pub const fn generic_signature(&self) -> Option<&GenericSignature> {
        self.generic_signature.as_ref()
    }

    /// Returns one inference result for each method in the class file.
    #[must_use]
    pub fn methods(&self) -> &[MethodInference] {
        &self.methods
    }

    /// Returns diagnostics emitted while analyzing the class.
    #[must_use]
    pub fn diagnostics(&self) -> &[Diagnostic] {
        &self.diagnostics
    }

    /// Returns whether every method reached a fixed point within configured limits.
    ///
    /// This does not hide instruction-level diagnostics; inspect
    /// [`Self::diagnostics`] for unsupported or malformed bytecode details.
    #[must_use]
    pub fn analysis_complete(&self) -> bool {
        self.methods.iter().all(MethodInference::analysis_complete)
    }

    pub(crate) fn mark_batch_analysis_incomplete(&mut self) {
        for method in &mut self.methods {
            method.mark_analysis_incomplete();
        }
        self.diagnostics.push(Diagnostic::new(
            crate::DiagnosticSeverity::Error,
            crate::DiagnosticKind::AnalysisLimitReached,
            crate::DiagnosticLocation::class_level(),
            "batch method-summary work-item budget was reached",
        ));
    }
}

/// Type-inference results for a caller-supplied batch of class files.
///
/// Entries retain the input order. Each JVM internal class name may occur only
/// once in a batch.
#[derive(Debug, Clone)]
pub struct ClassInferences {
    classes: Vec<ClassInference>,
}

impl ClassInferences {
    pub(crate) const fn new(classes: Vec<ClassInference>) -> Self {
        Self { classes }
    }

    /// Returns inference results in the same order as the input class files.
    #[must_use]
    pub fn classes(&self) -> &[ClassInference] {
        &self.classes
    }

    /// Returns the result for one JVM internal class name.
    #[must_use]
    pub fn get(&self, class_name: &ClassName) -> Option<&ClassInference> {
        self.classes
            .iter()
            .find(|inference| inference.class_name() == class_name)
    }

    /// Returns the number of analyzed class files.
    #[must_use]
    pub const fn len(&self) -> usize {
        self.classes.len()
    }

    /// Returns whether the batch contains no class files.
    #[must_use]
    pub const fn is_empty(&self) -> bool {
        self.classes.is_empty()
    }

    /// Returns whether analysis completed for every class in the batch.
    #[must_use]
    pub fn analysis_complete(&self) -> bool {
        self.classes.iter().all(ClassInference::analysis_complete)
    }
}

/// Type-inference results for one method.
///
/// Parameter and return types come from the method descriptor. Local-variable
/// and instruction states are inferred from the method's bytecode.
#[derive(Debug, Clone)]
pub struct MethodInference {
    name: String,
    descriptor: MethodDescriptor,
    generic_signature: Option<GenericSignature>,
    analysis_complete: bool,
    parameter_types: Vec<InferredType>,
    return_type: ReturnType,
    inferred_return_type: Option<InferredType>,
    returned_parameter_index: Option<usize>,
    local_types: Vec<InferredType>,
    instructions: Vec<InstructionInference>,
}

pub(crate) struct MethodHeader {
    pub(crate) descriptor: MethodDescriptor,
    pub(crate) generic_signature: Option<GenericSignature>,
    pub(crate) analysis_complete: bool,
    pub(crate) parameter_types: Vec<InferredType>,
    pub(crate) return_type: ReturnType,
    pub(crate) inferred_return_type: Option<InferredType>,
    pub(crate) returned_parameter_index: Option<usize>,
}

impl MethodInference {
    pub(crate) fn new(
        name: String,
        header: MethodHeader,
        local_types: Vec<InferredType>,
        instructions: Vec<InstructionInference>,
    ) -> Self {
        Self {
            name,
            descriptor: header.descriptor,
            generic_signature: header.generic_signature,
            analysis_complete: header.analysis_complete,
            parameter_types: header.parameter_types,
            return_type: header.return_type,
            inferred_return_type: header.inferred_return_type,
            returned_parameter_index: header.returned_parameter_index,
            local_types,
            instructions,
        }
    }

    /// Returns the method name as stored in the class file.
    #[must_use]
    pub fn name(&self) -> &str {
        &self.name
    }

    /// Returns the parsed JVM method descriptor.
    #[must_use]
    pub const fn descriptor(&self) -> &MethodDescriptor {
        &self.descriptor
    }

    /// Returns the method's generic `Signature` attribute, when present.
    #[must_use]
    pub const fn generic_signature(&self) -> Option<&GenericSignature> {
        self.generic_signature.as_ref()
    }

    /// Returns whether analysis reached a fixed point within configured limits.
    #[must_use]
    pub const fn analysis_complete(&self) -> bool {
        self.analysis_complete
    }

    /// Returns the descriptor-derived parameter types in declaration order.
    #[must_use]
    pub fn parameter_types(&self) -> &[InferredType] {
        &self.parameter_types
    }

    /// Returns the descriptor-derived method return type.
    #[must_use]
    pub const fn return_type(&self) -> &ReturnType {
        &self.return_type
    }

    /// Returns the inferred value type observed at reachable value-return instructions.
    ///
    /// This is more precise than [`Self::return_type`] when a method declares a
    /// broad reference type but consistently returns a narrower one. `None`
    /// means the method is void, did not reach a value return, or did not reach
    /// a complete, descriptor-compatible fixed point.
    #[must_use]
    pub const fn inferred_return_type(&self) -> Option<&InferredType> {
        self.inferred_return_type.as_ref()
    }

    /// Returns the parameter index returned unchanged by every reachable value return.
    ///
    /// This enables direct-call inference to use an argument's actual type. The
    /// index is in declaration order and excludes an instance method's implicit
    /// `this` receiver. `None` means no single parameter source was proven.
    #[must_use]
    pub const fn returned_parameter_index(&self) -> Option<usize> {
        self.returned_parameter_index
    }

    pub(crate) fn mark_analysis_incomplete(&mut self) {
        self.analysis_complete = false;
        self.inferred_return_type = None;
        self.returned_parameter_index = None;
    }

    /// Returns inferred local-variable types indexed by JVM local slot.
    ///
    /// Aggregates the types observed across the method, including separate
    /// lifetimes of a reused slot. Distinct reference candidates are retained
    /// rather than collapsed to a hierarchy-derived common supertype here.
    #[must_use]
    pub fn local_types(&self) -> &[InferredType] {
        &self.local_types
    }

    /// Returns type states for modeled bytecode instructions.
    #[must_use]
    pub fn instructions(&self) -> &[InstructionInference] {
        &self.instructions
    }
}

/// Inferred abstract state at one bytecode instruction.
///
/// The local-variable and operand-stack slices describe the state immediately
/// before and immediately after the instruction at [`Self::bytecode_offset`].
#[derive(Debug, Clone)]
pub struct InstructionInference {
    bytecode_offset: u16,
    dynamic_call_kind: Option<DynamicCallKind>,
    operand_expectations: Vec<OperandExpectation>,
    local_types: std::sync::Arc<[InferredType]>,
    stack_before: Vec<InferredType>,
    stack_after: Vec<InferredType>,
}

impl InstructionInference {
    pub(crate) fn new(
        bytecode_offset: u16,
        dynamic_call_kind: Option<DynamicCallKind>,
        operand_expectations: Vec<OperandExpectation>,
        local_types: std::sync::Arc<[InferredType]>,
        stack_before: Vec<InferredType>,
        stack_after: Vec<InferredType>,
    ) -> Self {
        Self {
            bytecode_offset,
            dynamic_call_kind,
            operand_expectations,
            local_types,
            stack_before,
            stack_after,
        }
    }

    /// Returns this instruction's offset within its method's `Code` attribute.
    #[must_use]
    pub const fn bytecode_offset(&self) -> u16 {
        self.bytecode_offset
    }

    /// Returns recognized bootstrap metadata for an `invokedynamic` instruction.
    #[must_use]
    pub const fn dynamic_call_kind(&self) -> Option<DynamicCallKind> {
        self.dynamic_call_kind
    }

    /// Returns verifier-derived requirements for operands consumed by this instruction.
    ///
    /// Each expectation names an index into [`Self::stack_before`]. The index
    /// uses that slice's bottom-to-top order. Member calls, `invokedynamic`,
    /// field stores, and value returns report constraints when their descriptors
    /// and a complete operand stack are available. This does not execute a
    /// bootstrap method or alter the observed inferred types.
    #[must_use]
    pub fn operand_expectations(&self) -> &[OperandExpectation] {
        &self.operand_expectations
    }

    /// Returns local-variable types immediately before this instruction.
    ///
    /// Values from different or unproven origins retain reference alternatives
    /// at joins. A reference hierarchy may refine joins of the same proven value.
    #[must_use]
    pub fn local_types(&self) -> &[InferredType] {
        &self.local_types
    }

    /// Returns operand-stack types immediately before this instruction.
    #[must_use]
    pub fn stack_before(&self) -> &[InferredType] {
        &self.stack_before
    }

    /// Returns operand-stack types immediately after this instruction.
    #[must_use]
    pub fn stack_after(&self) -> &[InferredType] {
        &self.stack_after
    }
}

/// A verifier-derived type requirement for one operand-stack value.
///
/// The index identifies a value in [`InstructionInference::stack_before`].
/// It is not an assertion that the observed value has one exact allocation
/// class: receiver requirements are assignability constraints.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OperandExpectation {
    stack_index: usize,
    constraint: OperandConstraint,
}

impl OperandExpectation {
    pub(crate) const fn new(stack_index: usize, constraint: OperandConstraint) -> Self {
        Self {
            stack_index,
            constraint,
        }
    }

    /// Returns the zero-based index in [`InstructionInference::stack_before`].
    #[must_use]
    pub const fn stack_index(&self) -> usize {
        self.stack_index
    }

    /// Returns the JVM requirement imposed on the value at [`Self::stack_index`].
    #[must_use]
    pub const fn constraint(&self) -> &OperandConstraint {
        &self.constraint
    }
}

/// The JVM type condition required for an instruction operand.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum OperandConstraint {
    /// The operand must have the category described by this JVM descriptor.
    Descriptor(TypeDescriptor),
    /// The operand is an instance receiver assignable to this member owner.
    ReceiverAssignableTo(ClassName),
}